Skip to Content

Wiki source code of Rancher 2

Last modified by Diana Strebkova on 2025/12/08 15:45
Show last authors
1 Rancher is a Kubernetes management tool to deploy and run clusters anywhere and on any provider.
2
3 The following page can only cover some special topics. Please read the [[official Rancher documentation >>url:https://ranchermanager.docs.rancher.com/||rel="nofollow" shape="rect" class="external-link"]] to learn more about Rancher 2 and how to perform container management.
4
5 {{toc/}}
6
7 = (% style="letter-spacing:-0.01em" %)Role mapping(%%) =
8
9 No special permissions are assigned to Portal Admins. Currently, the only users with elevated permissions are users with //at least one// Project Admin role. For more info check out the [[Roles>>url:https://prd.sdc.t-systems.net/confluence/display/SDCLOUD/How+to+use+Rancher+2#HowtouseRancher2-Roles||shape="rect"]] chapter.
10
11 (% class="table-bordered" style="width:100.0%" %)
12 (% class="active" %)|=(% colspan="1" style="text-align: left;" %)(((
13 Project Role
14 )))|=(% colspan="1" style="text-align: left;" %)(((
15 Rancher 2 Global Role
16 )))|=(% colspan="1" style="text-align: left;" %)(((
17 Description
18 )))
19 |(% style="text-align:left" %)(((
20 Admin
21 )))|(% style="text-align:left" %)(((
22 Standard User
23 )))|(% colspan="1" style="text-align:left" %)(((
24 These users can create new clusters and use them. Standard users can also assign permissions for their clusters to other users.
25 )))
26 |(% style="text-align:left" %)(((
27 Master
28 )))|(% rowspan="3" style="text-align:left" %)(((
29 User-Base
30 )))|(% rowspan="3" style="text-align:left" %)(((
31 User-Base users have login-access only. But they can be added to clusters and namespaces.
32 )))
33 |(% style="text-align:left" %)(((
34 Developer
35 )))
36 |(% colspan="1" style="text-align:left" %)(((
37 Viewer
38 )))
39
40 = (% style="letter-spacing:-0.01em" %)Login to Rancher(%%) =
41
42 As a first step, go to the **Projects** page in the DevOps Portal, then click on Rancher2 in the **Tools** column of one of your projects:
43
44 (% class="confluence-embedded-file-wrapper confluence-embedded-manual-size" %)[[image:attach:Screenshot 2023-03-16 at 18.38.02.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="228" width="900"]]
45
46 Then login to Rancher using the Keycloak option.
47
48 [[image:attach:MicrosoftTeams-image (2).png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="453" width="900"]]
49
50 Click on the "Log in with Keycloak" button as shown in the above screenshot.
51
52 After you logged in, the welcome page will look different depending on the level of access you have.
53
54 These are the two options:
55
56 1. If you have at least one Project Admin Role you get **Standard User** global permissions in Rancher. This will also show the "Import Existing" and "Create" button (for adding a cluster)// //as seen in the screenshot below:
57 [[image:attach:MicrosoftTeams-image (3).png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="371" width="1000"]]
58
59 1. If you have no Project Admin Role, you get **User-Base** global permissions in Rancher. This means you cannot add new clusters. You will only see clusters for which somebody else has assigned you some permissions. The screenshot below shows how the welcome screen will look like:
60 [[image:attach:MicrosoftTeams-image (4).png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" width="1000"]]
61
62 = Roles =
63
64 == Global Roles ==
65
66 As mentioned, users will be a member of one of the following two Global Roles which contain Global Permissions.
67
68 (% class="table-bordered" %)
69 (% class="active" %)|=(% style="text-align: left;" %)(((
70 Display Name
71 )))|=(% style="text-align: left;" %)(((
72 Name
73 )))|=(% style="text-align: left;" %)(((
74 Permissions
75 )))
76 |(% style="text-align:left" %)(((
77 User-Base
78 )))|(% style="text-align:left" %)(((
79 user-base
80 )))|(% style="text-align:left" %)(((
81 * View/edit own preferences
82 * Create/manage personal API key
83 * View Global Settings (all sections)
84 )))
85 |(% colspan="1" style="text-align:left" %)(((
86 Standard User
87 )))|(% colspan="1" style="text-align:left" %)(((
88 user
89 )))|(% colspan="1" style="text-align:left" %)(((
90 * View/edit own preferences
91 * Create/manage personal API key
92 * View Global Settings (all sections)
93 * Create clusters (import or create)
94 * Cluster Management - See and manage own clusters
95 * Create Cloud Credentials
96 * View Cluster/Node drivers (Edit options are displayed but are not effective)
97 * Create new Cluster/Node drivers
98 * View PSP  (Create/Edit options are displayed but are not effective)
99 * View and Create PSA 
100 * View and Create RKE1 Node Templates
101 * View RKE1 cluster templates (Add option is displayed but not effective)
102 * View chart repo templates (relevance not clear)
103 )))
104
105 For more information regarding roles and permissions for Rancher 2 please access the following link: [[https:~~/~~/ranchermanager.docs.rancher.com/>>url:https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions||shape="rect"]]
106
107 == Cluster and Project Roles ==
108
109 Global roles are assigned based on the project role in the DevOps portal. In addition, roles at cluster or "project" level can be assigned, too. These roles are assigned within the Rancher UI and are not derived from any role in the DevOps portal.
110
111 {{info}}
112 The term "project" within Rancher has a different meaning than used in the DevOps portal. Within Rancher, a project is a collection of namespaces with some configuration, including roles for specific users.
113 {{/info}}
114
115 === Cluster Roles ===
116
117 Cluster roles define permissions for individual users for a specific cluster, see this [[Link>>url:https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles#cluster-roles||shape="rect"]] for further information from Rancher.
118
119 {{info}}
120 Cluster roles can only be granted by the cluster owner who created or imported the cluster.
121 {{/info}}
122
123 If roles shall be assigned to created or imported clusters, then follow this procedure:
124
125 1. Go to the Rancher homepage, where you see the list of managed clusters
126 1. Click on the "Manage" button, the Cluster Management page is opened
127 1. Click on the 3 dots on the right side of the line with the intended cluster → Click on "Edit config"
128 1. Extend "Member Roles" and Click on "Add Member".
129 [[image:attach:image-2023-4-25_11-2-51.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="254" width="646"]]
130 1. Start typing the full name of the user. There should be a suggestion displayed. Click on it.
131 1. In the role field, choose one of the built-in roles, see this [[Link>>url:https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles#cluster-roles||shape="rect"]] for the description of permissions per role.
132 1. Click on Save at the bottom of the page.
133
134 === Project Roles ===
135
136 Within a cluster, roles can be assigned for individual Rancher projects. This allows a more granular permission assignment within a cluster. See this [[Link>>url:https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles#project-roles||shape="rect"]] for further information.
137
138 {{info}}
139 Project roles can only be granted by a user with a sufficient role within the cluster.
140 {{/info}}
141
142 Follow this instruction to assign project roles to individual users:
143
144 1. In Rancher UI, switch to the cluster in which a project role shall be assigned.
145 1. In the menu on the left side, click on Cluster/Projects+Namespaces.
146 1. Switch to "Group by Project" presentation
147 [[image:attach:image-2023-4-25_11-13-6.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="113" width="934"]]
148 1. Search and find the project, for which you want to assign roles
149 1. In the line of this project (not the line with a namespace), click on the 3 dots on the right side → Click on Edit Config
150 1. Click on the Add (Members) button
151 [[image:attach:image-2023-4-25_11-16-29.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" width="400"]]
152 1. Start typing the full name of the user in the Select Member Field. There should be a suggestion displayed. Click on the entry with the full name (Local)
153 1. In the Project Permission field, select the intended role, see this [[Link>>url:https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles#project-roles||shape="rect"]] for further information.
154 1. Click on "Add".
155 1. Click on "Save" at the bottom of the page when all intended users have been are added.
156
157 = Helm charts =
158
159 == Add public helm chart ==
160
161 {{warning width="70" title="Chartmuseum Deprecation"}}
162 Chartmuseum is deprecated in new Harbor versions, we are migrating all helm charts to oci-compatible repositories in Harbor! New approach to add chart repositories in rancher.
163 {{/warning}}
164
165 In this section, we describe (% style="color:#172b4d" %)how to add public helm charts like the one of DevOps-as-a-Service to a cluster to allow manual deployments.
166
167 (% id="HCreateAppRepositoryinRancher" class="p1" %)
168 === Create Chart Repository in Rancher ===
169
170 (% class="p1" %)
171 In Rancher UI, switch to the intended cluster and go to Apps/Repositories using the left side menu.
172 [[image:attach:Screenshot 2023-04-25 at 13.11.48.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="400" width="209"]]
173
174 (% class="p1" %)
175 Create a new Repository by clicking the Create button.
176
177 (% class="p1" %)
178 [[image:attach:Screenshot 2023-04-25 at 13.30.33.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="127" width="1100"]]
179
180 (% id="H" class="p1" %)
181 ==== Target: http(s) URL ====
182
183 {{warning}}
184 This example is being deprecated, you can still add other external repositories in that way, but all internal harbor-hosted repositories should be added as Target: OCI Repository
185 {{/warning}}
186
187 (% class="p1" %)
188 In the "Repository: Create" dialog, simply fill in the following fields. Authentication is not required.
189
190 (% class="wrapped" %)
191 |=(((
192 Field
193 )))|=(((
194 Value
195 )))
196 |=(((
197 Name
198 )))|(((
199 devops-as-a-service
200 )))
201 |=(((
202 Description
203 )))|(((
204 Public Helm charts as documented at [[https:~~/~~/docs.devops.t-systems.net>>url:https://docs.devops.t-systems.net||shape="rect"]]
205 )))
206 |=(((
207 Index URL
208 )))|(((
209 [[https:~~/~~/registry.sdc.t-systems.net/chartrepo/devopsaas/>>url:https://registry.sdc.t-systems.net/chartrepo/devopsaas/||shape="rect"]]
210 )))
211
212 [[image:attach:image-2024-2-27_14-29-17.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" width="540"]]
213
214 (% class="p1" %)
215 Finally, click Create.
216
217 The repository is now listed:
218
219 [[image:Screenshot 2024-07-03 at 15.13.55.png||data-xwiki-image-style-border="true" height="149" width="785"]]
220
221 ==== Target: OCI Repository ====
222
223 To add public oci-repository, navigate to repository create button and click it.
224
225 [[image:1765207154466-828.png||height="298" width="821"]]
226
227 In the "Repository: Create" dialog, simply fill in the following fields. Authentication is not required.
228
229 (% class="wrapped" %)
230 |=(((
231 Field
232 )))|=(((
233 Value
234 )))
235 |=(((
236 Name
237 )))|(((
238 devopsaas-jenkins-auto-agent
239 )))
240 |=(((
241 Description
242 )))|(((
243 Public Helm charts as documented at [[https:~~/~~/docs.devops.t-systems.net>>url:https://docs.devops.t-systems.net||shape="rect"]]
244 )))
245 |=(((
246 Index URL
247 )))|(((
248 oci:[[~~/~~/registry.sdc.t-systems.net/chartrepo/devopsaas-helm/>>url:https://registry.sdc.t-systems.net/chartrepo/devopsaas/||shape="rect"]]chartname, for example:
249
250 oci:[[~~/~~/registry.sdc.t-systems.net/>>url:https://registry.sdc.t-systems.net/chartrepo/devopsaas/||shape="rect"]][[devopsaas-helm/jenkins-lib>>url:https://registry-manoni.devops.t-systems.net/harbor/projects/139/repositories/jenkins-lib]]
251 )))
252
253 {{info}}
254 Now all internal helm charts are stored in harbor folders with -helm suffix. Adding the whole public project doesn't work natively anymore, so each separate chart should be added as a separate repo.
255 {{/info}}
256
257 === Deploy Helm charts ===
258
259 Now go to Apps>Charts and filter if necessary for the devops-as-a-service Helm chart repository. Like shown below, a list of available charts is displayed. Simply click on one of the tiles to deploy them to your cluster.
260
261 Please note that the jenkins-lib charts are only generated for testing purposes. It doesn't make sense to deploy them. Your Jenkins is automatically retrieving the Jenkinslib directly using [[Git>>url:https://prd.sdc.t-systems.net/bitbucket/projects/DEVOPSAAS/repos/sdcloud-caas-jenkins-libs/browse||shape="rect"]].
262
263 [[image:attach:image-2023-5-19_16-1-52.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" width="1100"]]
264
265 == Add private chart repository ==
266
267
268 === Create a robot account in Harbor ===
269
270 To add project specific helm charts to Rancher, a Harbor robot account is needed, that is able to read helm charts and pull repositories. If you don't have such an account yet, please follow the instructions given in the [[Create Robot Account section of the Harbor documentation>>doc:Harbor.Harbor 2\.7 Robot Accounts.WebHome||anchor="create_robot_account"]] and make sure to grant at least the following permissions:
271
272 * Read Helm Chart
273 * Pull Repository
274
275 (% id="HCreateAppRepositoryinRancher-1" class="p1" %)
276 === Create App Repository in Rancher ===
277
278 (% class="p1" %)
279 In Rancher UI, switch to the intended cluster and go to Apps/Repositories using the left side menu.
280 [[image:attach:Screenshot 2023-04-25 at 13.11.48.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="400" width="209"]]
281
282 (% class="p1" %)
283 Create a new Repository by pressing the Create button.
284
285 (% id="HTarget:http28s29URL-1" class="p1" %)
286 ==== [[image:attach:Screenshot 2023-04-25 at 13.30.33.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="127" width="1100"]] ====
287
288 (% class="p1" %)
289 ==== Target: http(s) URL ====
290
291 {{warning title="Chartmuseum Deprecation"}}
292 Chartmuseum in Harbor is deprecated, meaning we won't be able to add repositories to Rancher that way anymore. Instead use Target: OCI repository.
293 {{/warning}}
294
295 (% class="p1" %)
296 A name for the Repository has to be set. In the screenshot, the project name CITEST is used, which corresponds to our example from above.
297 Choose http(s) URL to an index generated by Helm and provide the Index URL ##https:~/~/registry-<domain>.devops.t-systems.net/chartrepo/<project>/##
298
299 (% class="p1" %)
300 Replace ##<domain>## and ##<project>## as necessary to match your set-up.
301
302 (% class="p1" %)
303 For Authentication, select "Create a HTTP Basic Auth Secret" and provide the Username and Password of the Harbor robot account from the previous section.
304 [[image:attach:Screenshot 2023-04-26 at 18.10.15.png||data-xwiki-image-style-border="true" queryparams="effects=drop-shadow" height="468" width="1100"]]
305
306 (% class="p1" %)
307 Click Create.
308
309 (% class="p1" %)
310 ==== Target: OCI Repository ====
311
312 {{info}}
313 Now all internal helm charts are stored in harbor folders with -helm suffix. Adding the whole public project doesn't work natively anymore, so each separate chart should be added as a separate repo.
314 {{/info}}
315
316 (% class="p1" %)
317 Choose OCI repository in Target and for url, use  ##oci:~/~/registry-<domain>.devops.t-systems.net/<project>-helm/<chatname>##
318
319 (% class="p1" %)
320 Replace ##<domain>## , ##<project>##  and ##<chatname> ##as necessary to match your set-up.
321
322 (% class="p1" %)
323 For Authentication, select "Create a HTTP Basic Auth Secret" and provide the Username and Password of the Harbor robot account from the previous section.
324
325 (% class="wikigeneratedid" %)
326 [[image:1765208347952-345.36.18.png||height="449" width="849"]]
327
328 (% class="wikigeneratedid" %)
329 Click Create.
330
331 = Automated deployments with Jenkins =
332
333 In this section, we describe(% style="color:#172b4d" %) how to set-up **automated builds, tests and deployments** for Jenkins.
334
335 == Prerequisites ==
336
337 In order to facilitate the connection between Jenkins and Rancher for the automatic deployments to be possible when a new software version is built, a new technical user to handle this action is required.
338
339 In case you don't have one, create a new technical user by following the instructions at [[Creating technical users>>doc:DevOps Portal for Admins.WebHome||anchor="creating_tech_users"]].
340
341 == (% style="color:#172b4d" %)Download kubeconfig(%%) ==
342
343 (% style="color:#172b4d" %)Connect to Rancher and navigate to your cluster, then in the right top menu, click "Download KubeConfig" as shown in the following image~:
344 [[image:attach:download_kubeconfig.png||height="150"]]
345
346 (% style="color:#172b4d" %)The downloaded kubeconfig file will have the same name as the cluster.
347
348 == Deploy kubeconfig to Jenkins ==
349
350 In order to be able to automatically deploy your software using Jenkins, follow the next steps:
351
352 * Login to your DevOps Portal account and click "Project Credentials" in the "Continuous Integration & Delivery" section.
353 [[image:image-2024-3-29_12-4-45.png||alt="https://prd.sdc.t-systems.net/confluence/download/attachments/118161601/image-2024-3-29_12-4-45.png?version=1&modificationDate=1711706685672&api=v2" data-xwiki-image-style-border="true" height="198"]]
354
355 * Click "Add Credentials"
356 * Upload the kubeconfig file:
357
358 [[image:image-2024-1-3_16-35-29.png||alt="https://prd.sdc.t-systems.net/confluence/download/attachments/118161601/image-2024-1-3_16-35-29.png?version=1&modificationDate=1704292529367&api=v2&effects=drop-shadow" data-xwiki-image-style-border="true" height="400"]]
359
360 * Choose "Secret file" from "Kind" dropdown
361 * Click "Browse" and select your previously downloaded kubeconfig file
362 * The "ID" field will be used in parameterized pipelines. We propose the prefix "kubeconfig-deployer-" followed by the project name (if the project name contains spaces, please replace them with "-") in order to be consistent and to make a clear differentiation between credential destinations. In the end, this is our proposal and conduct to follow, but of course you are free to name the credentials as you decide it fits best in your organization.
363 * For the "Description" field we suggest to provide details about the destination and use of these credentials.
364 * At the end, click "Create"
365
366 == Create a build and deploy pipeline ==
367
368 An application - more precisely, a helm chart - can now be built, tested and deployed automatically from Jenkins using the [[Jenkins Shared Library>>doc:Jenkins.Jenkins Shared Library.WebHome]] provided by DevOps-as-a-Service. Import the ##sdcloud## library in your Jenkinsfile and call the ##sdcPipeline## script, like shown in the following snippet:
369
370 {{code language="groovy"}}
371 @Library('sdcloud') _
372
373 sdcPipeline()
374 {{/code}}
375
376 The example above will run the build & deploy pipeline with its default configuration, which means
377
378 * Only the build and test steps will be executed but the built helm chart won't be deployed. To also include the deployment step, set the ##deployHelmChart## parameter to ##true##:
379 {{code language="groovy"}}sdcPipeline(deployHelmChart: true){{/code}}
380
381 * The smoke test step expects a service responding with an HTTP 20x for a request sent to path "/" and port 80 using http. If your service uses different paths, ports, protocols, or arguments, set the corresponding ##sdcPipeline## parameters ##containerProtocol##, ##containerPort##, ##containerContextPath##, and ##containerArgs## accordingly. E.g. to adapt the protocol and the context path, do
382 {{code language="groovy"}}sdcPipeline(
383 containerPort: 8080,
384 containerContextPath: '/solarcalculator'
385 ){{/code}}
386
387 There is a lot more to customize. Please refer to [[the customization section of the Jenkins Shared Library documentation>>doc:Jenkins.Jenkins Shared Library.WebHome||anchor="pipeline_customization"]] for the full list of parameters.
© 2018-2025 T-Systems International GmbH