mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 04:58:07 +00:00
Remove unneeded intermediate folders
This commit is contained in:
Billy Tat
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: Advanced
|
||||
weight: 1000
|
||||
---
|
||||
|
||||
The documents in this section contain resources for less common use cases.
|
||||
+559
@@ -0,0 +1,559 @@
|
||||
---
|
||||
title: Enabling the API Audit Log to Record System Events
|
||||
weight: 4
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
- [Docker Install]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log)
|
||||
|
||||
- [Kubernetes Install]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#api-audit-log)
|
||||
|
||||
## API Audit Log Options
|
||||
|
||||
The usage below defines rules about what the audit log should record and what data it should include:
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| <a id="audit-level"></a>`AUDIT_LEVEL` | `0` - Disable audit log (default setting).<br/>`1` - Log event metadata.<br/>`2` - Log event metadata and request body.</br>`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value.<br/><br/>See [Audit Level Logging](#audit-log-levels) for a table that displays what each setting logs. |
|
||||
| `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. <br/><br/>Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`<br/> |
|
||||
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. |
|
||||
| `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. |
|
||||
| `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. |
|
||||
|
||||
<br/>
|
||||
|
||||
### Audit Log Levels
|
||||
|
||||
The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#audit-level) setting.
|
||||
|
||||
| `AUDIT_LEVEL` Setting | Request Metadata | Request Body | Response Metadata | Response 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
|
||||
|
||||
```bash
|
||||
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]({{<baseurl>}}/rancher/v2.6/en/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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Running on ARM64 (Experimental)"
|
||||
weight: 3
|
||||
---
|
||||
|
||||
> **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]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/other-installation-methods/single-node-docker) 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:
|
||||
>
|
||||
> - Manually find your version using https://github.com/rancher/rancher/releases.
|
||||
> - Go directly to your version using the tag and the specific version number. If you plan to use v2.5.8, for example, you may
|
||||
> navigate to https://github.com/rancher/rancher/releases/tag/v2.5.8.
|
||||
|
||||
- Create custom cluster and adding ARM64 based node(s)
|
||||
- Kubernetes cluster version must be 1.12 or higher
|
||||
- CNI Network Provider must be [Flannel]({{<baseurl>}}/rancher/v2.6/en/faq/networking/cni-providers/#flannel)
|
||||
- Importing clusters that contain ARM64 based nodes
|
||||
- Kubernetes cluster version must be 1.12 or higher
|
||||
|
||||
Please see [Cluster Options]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/options/) how to configure the cluster options.
|
||||
|
||||
The following features are not tested:
|
||||
|
||||
- Monitoring, alerts, notifiers, pipelines and logging
|
||||
- Launching apps from the catalog
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Tuning etcd for Large Installations
|
||||
weight: 2
|
||||
---
|
||||
|
||||
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](https://etcd.io/docs/v3.4.0/op-guide/maintenance/#space-quota) setting on the etcd servers.
|
||||
|
||||
### Example: This snippet of the RKE cluster.yml file increases the keyspace size to 5GB
|
||||
|
||||
```yaml
|
||||
# RKE cluster.yml
|
||||
---
|
||||
services:
|
||||
etcd:
|
||||
extra_args:
|
||||
quota-backend-bytes: 5368709120
|
||||
```
|
||||
|
||||
## Scaling etcd disk performance
|
||||
|
||||
You can follow the recommendations from [the etcd docs](https://etcd.io/docs/v3.4.0/tuning/#disk) 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 stripping 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.
|
||||
|
||||
```yaml
|
||||
# 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'
|
||||
```
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Opening Ports with firewalld
|
||||
weight: 1
|
||||
---
|
||||
|
||||
> We recommend disabling firewalld. For Kubernetes 1.19.x and higher, firewalld must be turned off.
|
||||
|
||||
Some distributions of Linux [derived from RHEL,](https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Rebuilds) 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]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/ports) for nodes in a high-availability Rancher server cluster.
|
||||
|
||||
# Prerequisite
|
||||
|
||||
Install v7.x or later ofv`firewalld`:
|
||||
|
||||
```
|
||||
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.
|
||||
+253
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Docker Install with TLS Termination at Layer-7 NGINX Load Balancer
|
||||
weight: 252
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
## Installation Outline
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
- [1. Provision Linux Host](#1-provision-linux-host)
|
||||
- [2. Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
|
||||
- [3. Configure Load Balancer](#3-configure-load-balancer)
|
||||
|
||||
<!-- /TOC -->
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements]({{<baseurl>}}/rancher/v2.6/en/installation/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](#advanced-options) below before continuing.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A-Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B-Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 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:
|
||||
|
||||
| Header | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `Host` | Hostname used to reach Rancher. | To identify the server requested by the client.
|
||||
| `X-Forwarded-Proto` | `https` | To identify the protocol that a client used to connect to the load balancer or proxy.<br /><br/>**Note:** If this header is present, `rancher/rancher` does not redirect HTTP to HTTPS.
|
||||
| `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that client used to connect to the load balancer or proxy.
|
||||
| `X-Forwarded-For` | IP 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](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/).
|
||||
|
||||
- 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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Single Node Backup and Restore]({{<baseurl>}}/rancher/v2.6/en/backups/docker-installs/). 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]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
For help troubleshooting certificates, see [this section.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/troubleshooting)
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### API Auditing
|
||||
|
||||
If you want to record all transactions with the Rancher API, enable the [API Auditing]({{<baseurl>}}/rancher/v2.6/en/installation/resources/advanced/api-audit-log) 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]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap), 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.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/#privileged-access-for-rancher-v2-5)
|
||||
|
||||
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](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-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;
|
||||
}
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Bootstrap Password
|
||||
weight: 800
|
||||
---
|
||||
|
||||
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:"
|
||||
```
|
||||
+101
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Choosing a Rancher Version
|
||||
weight: 1
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This section describes how to choose a Rancher version.
|
||||
|
||||
For a high-availability installation of Rancher, which is recommended for production, the Rancher server is installed using a **Helm chart** on a Kubernetes cluster. Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.6/en/installation/resources/helm-version) to choose a version of Helm to install Rancher.
|
||||
|
||||
For Docker installations of Rancher, which is used for development and testing, you will install Rancher as a **Docker image**.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Helm Charts">
|
||||
|
||||
When installing, upgrading, or rolling back Rancher Server when it is [installed on a Kubernetes cluster]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.
|
||||
|
||||
Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.6/en/installation/resources/helm-version) to choose a version of Helm to install Rancher.
|
||||
|
||||
### Helm Chart Repositories
|
||||
|
||||
Rancher provides several different Helm chart repositories to choose from. We align our latest and stable Helm chart repositories with the Docker tags that are used for a Docker installation. Therefore, the `rancher-latest` repository will contain charts for all the Rancher versions that have been tagged as `rancher/rancher:latest`. When a Rancher version has been promoted to the `rancher/rancher:stable`, it will get added to the `rancher-stable` repository.
|
||||
|
||||
| Type | Command to Add the Repo | Description of the Repo |
|
||||
| -------------- | ------------ | ----------------- |
|
||||
| rancher-latest | `helm repo add rancher-latest https://releases.rancher.com/server-charts/latest` | Adds a repository of Helm charts for the latest versions of Rancher. We recommend using this repo for testing out new Rancher builds. |
|
||||
| rancher-stable | `helm repo add rancher-stable https://releases.rancher.com/server-charts/stable` | Adds a repository of Helm charts for older, stable versions of Rancher. We recommend using this repo for production environments. |
|
||||
| rancher-alpha | `helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha` | Adds a repository of Helm charts for alpha versions of Rancher for previewing upcoming releases. These releases are discouraged in production environments. Upgrades _to_ or _from_ charts in the rancher-alpha repository to any other chart, regardless or repository, aren't supported. |
|
||||
|
||||
<br/>
|
||||
Instructions on when to select these repos are available below in [Switching to a Different Helm Chart Repository](#switching-to-a-different-helm-chart-repository).
|
||||
|
||||
> **Note:** All charts in the `rancher-stable` repository will correspond with any Rancher version tagged as `stable`.
|
||||
|
||||
### Helm Chart Versions
|
||||
|
||||
Rancher Helm chart versions match the Rancher version (i.e `appVersion`). Once you've added the repo you can search it to show available versions with the following command:<br/>
|
||||
`helm search repo --versions`
|
||||
|
||||
If you have several repos you can specify the repo name, ie. `helm search repo rancher-stable/rancher --versions` <br/>
|
||||
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:<br/>
|
||||
`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.
|
||||
|
||||
{{< release-channel >}}
|
||||
|
||||
1. List the current Helm chart repositories.
|
||||
|
||||
```plain
|
||||
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.
|
||||
|
||||
```plain
|
||||
helm repo remove rancher-<CHART_REPO>
|
||||
```
|
||||
|
||||
3. Add the Helm chart repository that you want to start installing Rancher from.
|
||||
|
||||
```plain
|
||||
helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
4. Continue to follow the steps to [upgrade Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/upgrades) from the new Helm chart repository.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Images">
|
||||
|
||||
When performing [Docker installs]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher.
|
||||
|
||||
### Server Tags
|
||||
|
||||
Rancher Server is distributed as a Docker image, which have tags attached to them. You can specify this tag when entering the command to deploy Rancher. Remember that if you use a tag without an explicit version (like `latest` or `stable`), you must explicitly pull a new version of that image tag. Otherwise, any image cached on the host will be used.
|
||||
|
||||
| Tag | Description |
|
||||
| -------------------------- | ------ |
|
||||
| `rancher/rancher:latest` | Our latest development release. These builds are validated through our CI automation framework. These releases are not recommended for production environments. |
|
||||
| `rancher/rancher:stable` | Our newest stable release. This tag is recommended for production. |
|
||||
| `rancher/rancher:<v2.X.X>` | You can install specific versions of Rancher by using the tag from a previous release. See what's available at DockerHub. |
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported.
|
||||
> - Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). Caveat: Alpha releases cannot be upgraded to or from any other release.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: About Custom CA Root Certificates
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
- [Docker install Custom CA certificate options]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker/advanced/#custom-ca-certificate)
|
||||
|
||||
- [Kubernetes install options for Additional Trusted CAs]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/chart-options/#additional-trusted-cas)
|
||||
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Continuous Delivery
|
||||
weight: 3
|
||||
---
|
||||
|
||||
As of Rancher v2.5, [Fleet]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/)
|
||||
|
||||
Environment Variable Key | Default Value | Description
|
||||
---|---|---
|
||||
`continuous-delivery` | `true` | This 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.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Allow Unsupported Storage Drivers
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/)
|
||||
|
||||
Environment Variable Key | Default Value | Description
|
||||
---|---|---
|
||||
`unsupported-storage-drivers` | `false` | This 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:
|
||||
|
||||
Name | Plugin
|
||||
--------|----------
|
||||
Amazon EBS Disk | `aws-ebs`
|
||||
AzureFile | `azure-file`
|
||||
AzureDisk | `azure-disk`
|
||||
Google Persistent Disk | `gce-pd`
|
||||
Longhorn | `flex-volume-longhorn`
|
||||
VMware vSphere Volume | `vsphere-volume`
|
||||
Local | `local`
|
||||
Network File System | `nfs`
|
||||
hostPath | `host-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:
|
||||
|
||||
Name | Plugin
|
||||
--------|--------
|
||||
Amazon EBS Disk | `aws-ebs`
|
||||
AzureFile | `azure-file`
|
||||
AzureDisk | `azure-disk`
|
||||
Google Persistent Disk | `gce-pd`
|
||||
Longhorn | `flex-volume-longhorn`
|
||||
VMware vSphere Volume | `vsphere-volume`
|
||||
Local | `local`
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Enabling Experimental Features
|
||||
weight: 17
|
||||
---
|
||||
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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/enable-not-default-storage-drivers) 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:
|
||||
|
||||
- [Enable features when starting Rancher.](#enabling-features-when-starting-rancher) When installing Rancher with a CLI, you can use a feature flag to enable a feature by default.
|
||||
- [Enable features from the Rancher UI](#enabling-features-with-the-rancher-ui) by going to the **Settings** page.
|
||||
- [Enable features with the Rancher API](#enabling-features-with-the-rancher-api) after installing Rancher.
|
||||
|
||||
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.
|
||||
|
||||
> **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]({{<baseurl>}}/rancher/v2.6/en/virtualization-admin/#feature-flag/).
|
||||
- `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]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/fleet) 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.](./continuous-delivery).
|
||||
- `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]({{<baseurl>}}/rancher/v2.6/en/api/api-tokens) for more information.
|
||||
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/enable-not-default-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,]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/istio-virtual-service-ui) 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 Name | Default Value | Status | Available as of | Rancher Restart Required? |
|
||||
| ----------------------------- | ------------- | ------------ | --------------- |---|
|
||||
| `istio-virtual-service-ui` | `false` | Experimental | v2.3.0 | |
|
||||
| `istio-virtual-service-ui` | `true` | GA* | v2.3.2 | |
|
||||
| `unsupported-storage-drivers` | `false` | Experimental | v2.3.0 | |
|
||||
| `fleet` | `true` | GA* | v2.5.0 | |
|
||||
| `fleet` | `true` | Can no longer be disabled | v2.6.0 | N/A |
|
||||
| `continuous-delivery` | `true` | GA* | v2.6.0 | |
|
||||
| `token-hashing` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | |
|
||||
| `legacy` | `false` for new installs, `true` for upgrades | GA* | v2.6.0 | |
|
||||
| `multi-cluster-management` | `false` | GA* | v2.5.0 | |
|
||||
| `harvester` | `true` | Experimental | v2.6.1 | |
|
||||
| `rke2` | `true` | Experimental | v2.6.0 | |
|
||||
|
||||
\* Generally Available. This feature is included in Rancher and it is not experimental.
|
||||
|
||||
# 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.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/install-rancher)
|
||||
|
||||
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**.
|
||||
1. Click **Feature Flags**.
|
||||
1. 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**.
|
||||
1. Click **Feature Flags**. You will see a list of experimental features.
|
||||
1. 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`.
|
||||
1. 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.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **True**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is enabled.
|
||||
|
||||
### Disabling Features with the Rancher API
|
||||
|
||||
1. Go to `<RANCHER-SERVER-URL>/v3/features`.
|
||||
1. 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.
|
||||
1. In the upper left corner of the screen, under **Operations,** click **Edit**.
|
||||
1. In the **Value** drop-down menu, click **False**.
|
||||
1. Click **Show Request**.
|
||||
1. Click **Send Request**.
|
||||
1. Click **Close**.
|
||||
|
||||
**Result:** The feature is disabled.
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: UI for Istio Virtual Services and Destination Rules
|
||||
weight: 2
|
||||
---
|
||||
|
||||
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]({{<baseurl>}}/rancher/v2.6/en/istio/setup) in order to use the feature.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/)
|
||||
|
||||
Environment Variable Key | Default Value | Status | Available as of
|
||||
---|---|---|---
|
||||
`istio-virtual-service-ui` |`false` | Experimental | v2.3.0
|
||||
`istio-virtual-service-ui` | `true` | GA | v2.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.](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/)
|
||||
- **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.](https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule)
|
||||
|
||||
To see these tabs,
|
||||
|
||||
1. Click **☰ > Cluster Management**.
|
||||
1. Go to the cluster where Istio is installed and click **Explore**.
|
||||
1. In the left navigation bar, click **Istio**.
|
||||
1. You will see tabs for **Kiali** and **Jaeger**. From the left navigation bar, you can view and configure **Virtual Services** and **Destination Rules**.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Helm Version Requirements
|
||||
weight: 3
|
||||
---
|
||||
|
||||
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.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/resources/advanced/helm2/) 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](https://github.com/rancher/rke/releases) 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`.
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
title: Setting up a High-availability RKE Kubernetes Cluster
|
||||
shortTitle: Set up RKE Kubernetes
|
||||
weight: 3
|
||||
---
|
||||
|
||||
|
||||
This section describes how to install a Kubernetes cluster. This cluster should be dedicated to run only the Rancher server.
|
||||
|
||||
> 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.]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/)
|
||||
|
||||
> **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,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) a Kubernetes command-line tool.
|
||||
|
||||
Also install [RKE,]({{<baseurl>}}/rke/latest/en/installation/) 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.
|
||||
|
||||
```yaml
|
||||
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"
|
||||
```
|
||||
|
||||
<figcaption>Common RKE Nodes Options</figcaption>
|
||||
|
||||
| Option | Required | Description |
|
||||
| ------------------ | -------- | -------------------------------------------------------------------------------------- |
|
||||
| `address` | yes | The public DNS or IP address |
|
||||
| `user` | yes | A user that can run docker commands |
|
||||
| `role` | yes | List of Kubernetes roles assigned to the node |
|
||||
| `internal_address` | no | The private DNS or IP address for internal cluster traffic |
|
||||
| `ssh_key_path` | no | Path 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]({{<baseurl>}}/rke/latest/en/config-options/) for the full list of options and capabilities.
|
||||
>
|
||||
> For tuning your etcd cluster for larger Rancher installations, see the [etcd settings guide]({{<baseurl>}}/rancher/v2.6/en/installation/resources/advanced/etcd/).
|
||||
>
|
||||
> For more information regarding Dockershim support, refer to [this page]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/dockershim/)
|
||||
|
||||
### 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]({{<baseurl>}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `rancher-cluster.rkestate`: The [Kubernetes Cluster State file]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state), this file contains credentials for full access to the cluster.<br/><br/>_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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/troubleshooting/) page.
|
||||
|
||||
|
||||
### [Next: Install Rancher]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/)
|
||||
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
title: Setting up a High-availability RKE2 Kubernetes Cluster for Rancher
|
||||
shortTitle: Set up RKE2 for Rancher
|
||||
weight: 2
|
||||
---
|
||||
_Tested on v2.5.6_
|
||||
|
||||
This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.]({{<baseurl>}}/rancher/v2.6/en/overview/architecture-recommendations/#environment-for-kubernetes-installations)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in [this section.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha)
|
||||
|
||||
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.](https://rancher.com/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,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#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`:
|
||||
|
||||
```yml
|
||||
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](https://docs.rke2.io/cluster_access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 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.
|
||||
+120
@@ -0,0 +1,120 @@
|
||||
---
|
||||
title: Setting up a High-availability K3s Kubernetes Cluster for Rancher
|
||||
shortTitle: Set up K3s for Rancher
|
||||
weight: 2
|
||||
---
|
||||
|
||||
This section describes how to install a Kubernetes cluster according to the [best practices for the Rancher server environment.]({{<baseurl>}}/rancher/v2.6/en/overview/architecture-recommendations/#environment-for-kubernetes-installations)
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/)
|
||||
|
||||
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.](https://rancher.com/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.
|
||||
1. 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:
|
||||
```sh
|
||||
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`.
|
||||
|
||||
1. 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,](https://kubernetes.io/docs/tasks/tools/install-kubectl/#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`:
|
||||
|
||||
```yml
|
||||
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]({{<baseurl>}}/k3s/latest/en/cluster-access/) or the [official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) 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.
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: About High-availability Installations
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/overview/architecture)
|
||||
|
||||
### Recommended Architecture
|
||||
|
||||
- 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.
|
||||
|
||||
<figcaption>Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</figcaption>
|
||||
|
||||
<sup>Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers</sup>
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Setting up Nodes in Amazon EC2
|
||||
weight: 3
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers/)
|
||||
- **Create security group:** We also recommend setting up a security group for the Rancher nodes that complies with the [port requirements for Rancher nodes.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/#port-requirements)
|
||||
|
||||
### 2. Provision Instances
|
||||
|
||||
1. Log into the [Amazon AWS EC2 Console](https://console.aws.amazon.com/ec2/) 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.
|
||||
1. In the left panel, click **Instances**.
|
||||
1. Click **Launch Instance**.
|
||||
1. 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**.
|
||||
1. In the **Step 2: Choose an Instance Type** section, select the `t2.medium` type.
|
||||
1. Click **Next: Configure Instance Details**.
|
||||
1. 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.
|
||||
1. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the **IAM role** field.
|
||||
1. Click **Next: Add Storage,** **Next: Add Tags,** and **Next: Configure Security Group**.
|
||||
1. In **Step 6: Configure Security Group,** select a security group that complies with the [port requirements]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/#port-requirements) for Rancher nodes.
|
||||
1. Click **Review and Launch**.
|
||||
1. Click **Launch**.
|
||||
1. 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.
|
||||
1. 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,](https://console.aws.amazon.com/ec2/) click **Instances** in the left panel.
|
||||
1. Go to the instance that you want to install Docker on. Select the instance and click **Actions > Connect**.
|
||||
1. 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,](https://github.com/rancher/install-docker) 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.
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: 'Set up Infrastructure for a High Availability K3s Kubernetes Cluster'
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation)
|
||||
|
||||
> **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.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node) 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](https://www.mysql.com/) 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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/rds/) 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.]({{<baseurl>}}/k3s/latest/en/installation/datastore/)
|
||||
|
||||
### 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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **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.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 'Set up Infrastructure for a High Availability RKE Kubernetes Cluster'
|
||||
weight: 2
|
||||
---
|
||||
|
||||
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](https://www.quora.com/What-is-split-brain-in-distributed-systems), 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.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node/) 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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **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.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: 'Set up Infrastructure for a High Availability RKE2 Kubernetes Cluster'
|
||||
weight: 1
|
||||
---
|
||||
|
||||
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.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/ec2-node) 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.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/chart-options/#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nginx/)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/nlb/)
|
||||
|
||||
> **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.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer)
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials.
|
||||
shortTitle: Infrastructure Tutorials
|
||||
weight: 5
|
||||
---
|
||||
|
||||
To set up infrastructure for a high-availability K3s Kubernetes cluster with an external DB, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db/)
|
||||
|
||||
|
||||
To set up infrastructure for a high-availability RKE Kubernetes cluster, refer to [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha/)
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Setting up an NGINX Load Balancer
|
||||
weight: 4
|
||||
---
|
||||
|
||||
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](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/).
|
||||
|
||||
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](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options.
|
||||
|
||||
<figcaption>Example NGINX config</figcaption>
|
||||
```
|
||||
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
|
||||
```
|
||||
+179
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: Setting up Amazon ELB Network Load Balancer
|
||||
weight: 5
|
||||
---
|
||||
|
||||
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](#1-create-target-groups)
|
||||
2. [Register Targets](#2-register-targets)
|
||||
3. [Create Your NLB](#3-create-your-nlb)
|
||||
4. [Add listener to NLB for TCP port 80](#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](https://console.aws.amazon.com/ec2/) to get started. Make sure to select the **Region** where your EC2 instances (Linux nodes) are created.
|
||||
1. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**.
|
||||
1. 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.](#health-check-paths-for-nginx-ingress-and-traefik-ingresses)
|
||||
|
||||
### Target Group (TCP port 443)
|
||||
|
||||
Configure the first target group according to the table below.
|
||||
|
||||
| Option | Setting |
|
||||
|-------------------|-------------------|
|
||||
| Target Group Name | `rancher-tcp-443` |
|
||||
| Target type | `instance` |
|
||||
| Protocol | `TCP` |
|
||||
| Port | `443` |
|
||||
| VPC | Choose your VPC |
|
||||
|
||||
Health check settings:
|
||||
|
||||
| Option | Setting |
|
||||
|---------------------|-----------------|
|
||||
| Protocol | TCP |
|
||||
| Port | `override`,`80` |
|
||||
| Healthy threshold | `3` |
|
||||
| Unhealthy threshold | `3` |
|
||||
| Timeout | `6 seconds` |
|
||||
| Interval | `10 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.
|
||||
|
||||
| Option | Setting |
|
||||
|-------------------|------------------|
|
||||
| Target Group Name | `rancher-tcp-80` |
|
||||
| Target type | `instance` |
|
||||
| Protocol | `TCP` |
|
||||
| Port | `80` |
|
||||
| VPC | Choose your VPC |
|
||||
|
||||
|
||||
Health check settings:
|
||||
|
||||
| Option |Setting |
|
||||
|---------------------|----------------|
|
||||
| Protocol | TCP |
|
||||
| Port | `traffic port` |
|
||||
| Healthy threshold | `3` |
|
||||
| Unhealthy threshold | `3` |
|
||||
| Timeout | `6 seconds` |
|
||||
| Interval | `10 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**.
|
||||
|
||||
{{< img "/img/rancher/ha/nlb/edit-targetgroup-443.png" "Edit target group 443">}}
|
||||
|
||||
Select the instances (Linux nodes) you want to add, and click **Add to registered**.
|
||||
|
||||
<hr>
|
||||
**Screenshot Add targets to target group TCP port 443**<br/>
|
||||
|
||||
{{< img "/img/rancher/ha/nlb/add-targets-targetgroup-443.png" "Add targets to target group 443">}}
|
||||
|
||||
<hr>
|
||||
**Screenshot Added targets to target group TCP port 443**<br/>
|
||||
|
||||
{{< img "/img/rancher/ha/nlb/added-targets-targetgroup-443.png" "Added targets to target group 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-create-target-groups).
|
||||
|
||||
1. From your web browser, navigate to the [Amazon EC2 Console](https://console.aws.amazon.com/ec2/).
|
||||
|
||||
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](#step-1-configure-load-balancer)
|
||||
- [Step 2: Configure Routing](#step-2-configure-routing)
|
||||
- [Step 3: Register Targets](#step-3-register-targets)
|
||||
- [Step 4: Review](#step-4-review)
|
||||
|
||||
### 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**.
|
||||
1. From the **Name** drop-down, choose `rancher-tcp-443`.
|
||||
1. 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](https://docs.traefik.io/operations/ping/) 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](https://github.com/kubernetes/ingress-nginx/blob/0cbe783f43a9313c9c26136e888324b1ee91a72f/charts/ingress-nginx/values.yaml#L212) 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.
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Setting up a MySQL Database in Amazon RDS
|
||||
weight: 4
|
||||
---
|
||||
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](https://console.aws.amazon.com/rds/) to get started. Make sure to select the **Region** where your EC2 instances (Linux nodes) are created.
|
||||
1. In the left panel, click **Databases**.
|
||||
1. Click **Create database**.
|
||||
1. In the **Engine type** section, click **MySQL**.
|
||||
1. In the **Version** section, choose **MySQL 5.7.22**.
|
||||
1. In **Settings** section, under **Credentials Settings,** enter a master password for the **admin** master username. Confirm the password.
|
||||
1. 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.
|
||||
1. 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.]({{<baseurl>}}/k3s/latest/en/installation/datastore/)
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "Don't have a Kubernetes cluster? Try one of these tutorials."
|
||||
weight: 4
|
||||
---
|
||||
|
||||
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.
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Setting up Local System Charts for Air Gapped Installations
|
||||
weight: 120
|
||||
---
|
||||
|
||||
The [System Charts](https://github.com/rancher/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]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap) instructions for Docker and Helm installs.
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Resources
|
||||
weight: 5
|
||||
---
|
||||
|
||||
### Docker Installations
|
||||
|
||||
The [single-node Docker installation]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/single-node-docker) 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]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap) 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:
|
||||
|
||||
- [Custom CA Certificate]({{<baseurl>}}/rancher/v2.6/en/installation/resources/custom-ca-root-certificate/)
|
||||
- [API Audit Log]({{<baseurl>}}/rancher/v2.6/en/installation/resources/advanced/api-audit-log/)
|
||||
- [TLS Settings]({{<baseurl>}}/rancher/v2.6/en/installation/resources/tls-settings/)
|
||||
- [etcd configuration]({{<baseurl>}}/rancher/v2.6/en/installation/resources/advanced/etcd/)
|
||||
- [Local System Charts for Air Gap Installations]({{<baseurl>}}/rancher/v2.6/en/installation/resources/local-system-charts) | v2.3.0 |
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Adding TLS Secrets
|
||||
weight: 2
|
||||
---
|
||||
|
||||
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](https://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]({{<baseurl>}}/rancher/v2.6/en/installation/resources/update-rancher-cert) to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) or to switch from the default self-signed certificate to a custom certificate.
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: TLS Settings
|
||||
weight: 3
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
* nginx-ingress-controller (default for RKE1 and RKE2): [Default TLS Version and Ciphers](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers).
|
||||
* traefik (default for K3s): [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options).
|
||||
|
||||
# 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:
|
||||
|
||||
| Parameter | Description | Default | Available options |
|
||||
|-----|-----|-----|-----|
|
||||
| `CATTLE_TLS_MIN_VERSION` | Minimum TLS version | `1.2` | `1.0`, `1.1`, `1.2`, `1.3` |
|
||||
| `CATTLE_TLS_CIPHERS` | Allowed TLS cipher suites | `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`,<br/>`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`,<br/>`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`,<br/>`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`,<br/>`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`,<br/>`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` | See [Golang tls constants](https://golang.org/pkg/crypto/tls/#pkg-constants) |
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: Troubleshooting the Rancher Server Kubernetes Cluster
|
||||
weight: 276
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
- [Is Rancher Running](#check-if-rancher-is-running)
|
||||
- [Cert CN is "Kubernetes Ingress Controller Fake Certificate"](#cert-cn-is-kubernetes-ingress-controller-fake-certificate)
|
||||
|
||||
### 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`](#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](https://docs.docker.com/install/linux/linux-postinstall/#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](https://bugzilla.redhat.com/show_bug.cgi?id=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](https://docs.docker.com/install/linux/linux-postinstall/#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`.
|
||||
+251
@@ -0,0 +1,251 @@
|
||||
---
|
||||
title: Updating the Rancher Certificate
|
||||
weight: 10
|
||||
---
|
||||
|
||||
# Updating a Private CA Certificate
|
||||
|
||||
Follow these steps to update the SSL certificate of the ingress in a Rancher [high availability Kubernetes installation]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/) 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 (<b>User > API & Keys</b>) 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](https://rancher.com/docs/rancher/v2.6/en/cluster-admin/cluster-access/ace/) 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]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/fleet/#accessing-fleet-in-the-rancher-ui) 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
|
||||
|
||||
>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]({{<baseurl>}}/rancher/v2.6/en/user-settings/api-keys/#creating-an-api-key) (<b>User > API & Keys</b>).
|
||||
|
||||
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]({{<baseurl>}}/rancher/v2.6/en/deploy-across-clusters/fleet/#accessing-fleet-in-the-rancher-ui) 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.
|
||||
+246
@@ -0,0 +1,246 @@
|
||||
---
|
||||
title: Upgrading Cert-Manager
|
||||
weight: 4
|
||||
---
|
||||
|
||||
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.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753)
|
||||
1. [Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/). This change has no exact deadline.
|
||||
1. [Cert-manager is deprecating `v1alpha1` API and replacing its API group](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/)
|
||||
|
||||
To address these changes, this guide will do two things:
|
||||
|
||||
1. Document the procedure for upgrading cert-manager
|
||||
1. Explain the cert-manager API changes and link to cert-manager's official documentation for migrating your data
|
||||
|
||||
> **Important:**
|
||||
> If you are currently running the cert-manager whose version is 1.5 or below, and want to upgrade both Rancher and cert-manager to a new version (1.6+ in the case of cert-manager), then you need to re-install both Rancher and cert-manager due to the API change in cert-manager 1.6. This will also be necessary if you are upgrading from a version of cert manager below 0.11 to a version of cert-manager above 0.11. Follow the steps below:
|
||||
|
||||
> 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.
|
||||
|
||||
# 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
|
||||
|
||||
<details id="normal">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
1. [Back up existing resources](https://cert-manager.io/docs/tutorials/backup/) as a precaution
|
||||
|
||||
```plain
|
||||
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.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)
|
||||
|
||||
1. [Uninstall existing deployment](https://cert-manager.io/docs/installation/uninstall/kubernetes/#uninstalling-with-helm)
|
||||
|
||||
```plain
|
||||
helm uninstall cert-manager
|
||||
```
|
||||
|
||||
Delete the CustomResourceDefinition using the link to the version vX.Y.Z you installed
|
||||
|
||||
```plain
|
||||
kubectl delete -f https://github.com/jetstack/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
kubectl apply --validate=false -f https://github.com/jetstack/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.
|
||||
|
||||
1. Create the namespace for cert-manager if needed
|
||||
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Add the Jetstack Helm repository
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
```
|
||||
|
||||
1. Update your local Helm chart repository cache
|
||||
|
||||
```plain
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Install the new version of cert-manager
|
||||
|
||||
```plain
|
||||
helm install \
|
||||
cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v0.12.0
|
||||
```
|
||||
|
||||
1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option B: Upgrade cert-manager in an Air Gap Environment
|
||||
|
||||
<details id="airgap">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
### 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]({{<baseurl>}}/rancher/v2.6/en/installation/other-installation-methods/air-gap/populate-private-registry) with the images needed for the upgrade.
|
||||
|
||||
1. From a system connected to the internet, add the cert-manager repo to Helm
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager).
|
||||
|
||||
```plain
|
||||
helm fetch jetstack/cert-manager --version v0.12.0
|
||||
```
|
||||
|
||||
1. 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:
|
||||
|
||||
```plain
|
||||
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:
|
||||
|
||||
```plain
|
||||
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
|
||||
```
|
||||
|
||||
1. Download the required CRD file for cert-manager (old and new)
|
||||
|
||||
```plain
|
||||
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
|
||||
|
||||
```plain
|
||||
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.](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/#additional-annotation-changes)
|
||||
|
||||
1. Delete the existing cert-manager installation
|
||||
|
||||
```plain
|
||||
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
|
||||
|
||||
```plain
|
||||
kubectl delete -f cert-manager/cert-manager-crd-old.yaml
|
||||
```
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
|
||||
```plain
|
||||
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.
|
||||
|
||||
1. Create the namespace for cert-manager
|
||||
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Install cert-manager
|
||||
|
||||
```plain
|
||||
kubectl -n cert-manager apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)
|
||||
|
||||
```plain
|
||||
kubectl apply -f cert-manager-backup.yaml
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#4-install-cert-manager). For instructions on upgrading cert-manager from version 1.5 to 1.6, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.5-1.6/). For instructions on upgrading cert-manager from version 1.6 to 1.7, see the upstream cert-manager documentation [here](https://cert-manager.io/docs/installation/upgrading/upgrading-1.6-1.7/).
|
||||
|
||||
---
|
||||
|
||||
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](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
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](https://cert-manager.io/docs/installation/upgrading/upgrading-0.7-0.8/).
|
||||
|
||||
Details about the change and migration instructions can be found in the [cert-manager v0.10 to v0.11 upgrade instructions](https://cert-manager.io/docs/installation/upgrading/upgrading-0.10-0.11/).
|
||||
|
||||
More info about [cert-manager upgrade information](https://cert-manager.io/docs/installation/upgrading/).
|
||||
|
||||
Reference in New Issue
Block a user