diff --git a/content/rancher/v2.x/en/backups/restorations/_index.md b/content/rancher/v2.x/en/backups/restorations/_index.md index 88982fcc4bf..ccfb75a22e8 100644 --- a/content/rancher/v2.x/en/backups/restorations/_index.md +++ b/content/rancher/v2.x/en/backups/restorations/_index.md @@ -4,5 +4,5 @@ weight: 1010 --- If you lose the data on your Rancher Server, you can restore it if you have backups stored in a safe location. -- [Restoring Backups—Single Node Installs](./single-node-restoration/) -- [Restoring Backups—High Availablity Installs](./ha-restoration/) \ No newline at end of file +- [Restoring Backups—Single Node Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/single-node-restoration/) +- [Restoring Backups—High Availability Installs]({{< baseurl >}}/rancher/v2.x/en/backups/restorations/ha-restoration/) diff --git a/content/rancher/v2.x/en/backups/restorations/ha-restoration/_index.md b/content/rancher/v2.x/en/backups/restorations/ha-restoration/_index.md index e60dbcc1c59..1dea8ac3a97 100644 --- a/content/rancher/v2.x/en/backups/restorations/ha-restoration/_index.md +++ b/content/rancher/v2.x/en/backups/restorations/ha-restoration/_index.md @@ -4,132 +4,162 @@ weight: 370 aliases: - /rancher/v2.x/en/installation/after-installation/ha-backup-and-restoration/ --- -This procedure describes how to restore your a snapshot of `etcd` if you lose your Rancher data in a disaster scenario. -## Restoration Outline +This procedure describes how to use RKE to restore a snapshot of the Rancher Kubernetes cluster. The cluster snapshot will include Kubernetes configuration and the Rancher database and state. -Following a disaster scenario, restoration of your HA Rancher installation requires you to pull your snapshot from your chosen external location and then restore it. +## Restore Outline -1. [Create New Nodes and Pull Snapshot and Certificates Bundle](#1-create-new-nodes-and-pull-snapshot-and-certificate-bundle) +1. [Preparation](#1-preparation) - If `etcd` nodes failed or quorum lost for any reason, you can create new nodes and restore the etcd snapshot and certificate bundle to it, first create the new nodes and then pull the most recent `etcd` snapshot to that node, and the most recent certificates pki bundle `pki.bundle.tar.gz` + Install utilities and create new or clean existing nodes to prepare for restore. -2. [Restore etcd Database](#2-restore-etcd-database) +2. [Place Snapshot and PKI Bundle](#2-place-snapshot-and-pki-bundle) - After you pull the snapshot and the certificates bundle, run the RKE command to restore the `etcd` database. + Pick a node and place snapshot `.db` and `pki.bundle.tar.gz` files. + +3. [Configure RKE](#3-configure-rke) + + Configure RKE `cluster.yml`. Remove `addons:` section and point configuration to the clean nodes. + +4. [Restore Database](#4-restore-database) + + Run RKE command to restore the `etcd` database to a single node. + +5. [Bring Up the Cluster](#5-bring-up-the-cluster) + + Run RKE commands to bring up cluster one a single node. Clean up old nodes. Verify and add additional nodes.
-### 1. Pull Snapshot and Certificates Bundle On New Nodes -If `etcd` nodes failed, you can either: +### 1. Preparation -- Create a new nodes of your choice—baremetal, on-prem virtual machine, cloud-based virtual machine, and so on. Provision it according to our [requirements]({{< baseurl >}}/rancher/v2.x/en/installation/ha-server-install/#host-requirements). +You will need [RKE]({{< baseurl >}}/rke/v0.1.x/en/installation/) and [kubectl]({{< baseurl >}}/rancher/v2.x/en/faq/kubectl/) CLI utilities installed. -- Use the existing nodes, but you should be make sure to clean each node using the following commands: +Prepare by creating 3 new nodes to be the target for the restored Rancher instance. See [HA Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/) for node requirements. + +We recommend that you start with fresh nodes and a clean state. Alternatively you can clear Kubernetes and Rancher configurations from the existing nodes. This will destroy the data on these nodes. See [Node Cleanup]({{< baseurl >}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) for the procedure. + +### 2. Place Snapshot and PKI Bundle + +Pick a one of the clean nodes. That node will be the "target node" for the initial restore. Place the snapshot and PKI certificate bundle files in the `/opt/rke/etcd-snapshots` directory on the "target node". + +* Snapshot - `.db` +* PKI Bundle - `pki.bundle.tar.gz` + +### 3. Configure RKE + +Make a copy of your original `rancher-cluster.yml` file. ``` -docker rm -fv $(docker ps -qa) -docker volume ls -q | xargs docker volume rm -rm -rf /etc/kubernetes/ssl -rm -rf /etc/kubernetes/.tmp -rm -rf /var/lib/etcd -rm -rf /etc/cni -rm -rf /etc/kube-flannel/ +cp rancher-cluster.yml rancher-cluster-restore.yml ``` -in both cases you will need to pull the most recent working `etcd` snapshot and the certificates bundle to these nodes. +Modify the copy and make the following changes. -**To Pull the Latest Snapshot and Certificates Bundle:** +* Remove or comment out entire the `addons:` section. The Rancher deployment and supporting configuration is already in the `etcd` database. +* Change your `nodes:` section to point to the restore nodes. +* Comment out the nodes that are not your "target node". We want the cluster to only start on that one node. -1. Log in to each new node using a remote Terminal connection. +*Example* `rancher-cluster-restore.yml` -2. Create a directory that mirrors your other nodes' snapshot directories: +```yaml +nodes: +- address: 52.15.238.179 # New Target Node + user: ubuntu + role: [ etcd, controlplane, worker ] +# - address: 52.15.23.24 +# user: ubuntu +# role: [ etcd, controlplane, worker ] +# - address: 52.15.238.133 +# user: ubuntu +# role: [ etcd, controlplane, worker ] - ``` - root@newnode:~# mkdir -p /opt/rke/etcd-snapshots - ``` +# addons: |- +# --- +# kind: Namespace +# apiVersion: v1 +# metadata: +# name: cattle-system +# --- +... -3. On each node, pull your most recent snapshot onto the node. Replace `` with the name of the snapshot you're restoring to. - - ``` - root@newnode:~# s3cmd get s3://rke-etcd-snapshots/ /opt/rke/etcd-snapshots/ - ``` - - >**Remember:** Our use of Amazon S3 is an example used for this documentation. The command for pulling your snapshot may vary. - -4. On each node, pull the most recent certificates pki bundle to the `/opt/rke/etcd-snapshots`: - - ``` - root@newnode:~# s3cmd get s3://rke-etcd-snapshots/pki.bundle.tar.gz /opt/rke/etcd-snapshots/pki.bundle.tar.gz - ``` - -### 2. Restore `etcd` Database - -To restore the most recent `etcd` snapshot on your new nodes, run RKE the command `rke etcd snapshot-restore`. This command reverts to any snapshot stored in `/opt/rke/etcd-snapshots` that you explicitly define. When you run `rke etcd snapshot-restore`, RKE removes the old `etcd` container if it still exists. To restore operations, RKE creates a new `etcd` cluster using the snapshot you choose, and extracts the certificate bundle to be used on the next `rke up` run. - ->**Warning:** Restoring an `etcd` snapshot deletes your current `etcd` cluster and replaces it with a new one. Before you run the `rke etcd snapshot-restore` command, backup any important data in your current cluster. -> ->**Prerequisites:** {{< requirements_rollback >}} - - -1. From your workstation, open `rancher-cluster.yml` in your favorite text editor. - -2. Replace the unresponsive nodes (`1.1.1.1`, `2.2.2.2`, `3.3.3.3` in this example) with your new one (`4.4.4.4`, `5.5.5.5`, and `6.6.6.6`). You IP addresses will be different obviously: -``` - nodes: - # - address: 1.1.1.1 # UNRESPONSIVE NODE - # user: root - # role: [controlplane,etcd,worker] - # ssh_key_path: ~/.ssh/id_rsa - # - address: 2.2.2.2 # UNRESPONSIVE NODE - # user: root - # role: [controlplane,etcd,worker] - # ssh_key_path: ~/.ssh/id_rsa - # - address: 3.3.3.3 # UNRESPONSIVE NODE - # user: root - # role: [controlplane,etcd,worker] - # ssh_key_path: ~/.ssh/id_rsa - - address: 4.4.4.4 # NEW NODE - user: root - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa - - address: 5.5.5.5 # NEW NODE - user: root - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa - - address: 6.6.6.6 # NEW NODE - user: root - role: [controlplane,etcd,worker] - ssh_key_path: ~/.ssh/id_rsa ``` -3. Save and close `rancher-cluster.yml`. +### 4. Restore Database -4. Open **Terminal** and change directory to the location of the RKE binary. Your `rancher-cluster.yml` file must reside in the same directory. +Use RKE with the new `rancher-cluster-restore.yml` configuration and restore the database to the single "target node". -5. Run one of the following commands to restore the `etcd` database: +``` +rke etcd snapshot-restore --name .db --config ./rancher-cluster-restore.yml +``` - ``` - # MacOS - ./rke_darwin-amd64 etcd snapshot-restore --name --config rancher-cluster.yml - # Linux - ./rke_linux-amd64 etcd snapshot-restore --name --config rancher-cluster.yml - ``` +> **NOTE:** RKE will create an `etcd` container with the restored database on the "target node". This container will not complete the `etcd` initialization and stay in a running state until the cluster brought up in the next step. +### 5. Bring Up the Cluster -6. Run one of the following commands to bring your cluster back up: +Use RKE and bring up the cluster on the single "target node". - ``` - # MacOS - ./rke_darwin-amd64 up --config rancher-cluster.yml - # Linux - ./rke_linux-amd64 up --config rancher-cluster.yml - ``` +``` +rke up --config ./rancher-cluster-restore.yml +``` -7. After restoring the cluster you have to restart the kubernetes components on all nodes, otherwise there will be some conflicts with resource versions of objects stored in `etcd`, this will include restart to kubernetes components and the network components, for more information please refer to [kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/#etcd-upgrade-requirements), to do that you can run the following on each node: +#### Testing the Cluster - ``` - docker restart kube-apiserver kubelet kube-controller-manager kube-scheduler kube-proxy - docker ps | grep flannel | cut -f 1 -d " " | xargs docker restart - docker ps | grep calico | cut -f 1 -d " " | xargs docker restart - ``` +Once RKE completes, the cluster should now be up and Rancher should be running. RKE will have created a credentials file in the local directory. Configure `kubectl` to use the `kube_config_rancher-cluster-restore.yml` credentials file and check on the state of the cluster. See [Installing and Configuring kubectl]({{< baseurl >}}/rancher/v2.x/en/faq/kubectl/#configuration) for details. + +You should see your new "target node" in `Ready` and three old nodes in `NotReady`. + +``` +kubectl get nodes + +NAME STATUS ROLES AGE VERSION +52.15.238.179 Ready controlplane,etcd,worker 1m v1.10.5 +18.217.82.189 NotReady controlplane,etcd,worker 16d v1.10.5 +18.222.22.56 NotReady controlplane,etcd,worker 16d v1.10.5 +18.191.222.99 NotReady controlplane,etcd,worker 16d v1.10.5 +``` + +#### Cleaning up Old Nodes + +Use `kubectl` to delete the old nodes from the cluster. Repeat for each old node. + +``` +kubectl delete node 18.217.82.189 +``` + +#### Adding in Additional Nodes + +Edit the `rancher-cluster-restore.yml` RKE config file and uncomment the additional nodes. + +*Example* `rancher-cluster-restore.yml` + +```yaml +nodes: +- address: 52.15.238.179 # New Target Node + user: ubuntu + role: [ etcd, controlplane, worker ] +- address: 52.15.23.24 + user: ubuntu + role: [ etcd, controlplane, worker ] +- address: 52.15.238.133 + user: ubuntu + role: [ etcd, controlplane, worker ] + +# addons: |- +# --- +# kind: Namespace +... + +``` + +Run RKE and add the nodes to the new cluster. + +``` +rke up --config ./rancher-cluster-restore.yml +``` + +#### Finishing Up + +Rancher should now be running and available to manage your Kubernetes clusters. Swap your Rancher DNS or Load Balancer endpoints to target the new cluster. Once this is done the agents on your managed clusters should automatically reconnect. This may take 10-15 minutes due to reconnect back off timeouts. + +> **IMPORTANT:** Remember to save your new RKE config (`rancher-cluster-restore.yml`) and `kubectl` credentials (`kube_config_rancher-cluster-restore.yml`) files in a safe place for future maintenance. diff --git a/content/rancher/v2.x/en/faq/kubectl/_index.md b/content/rancher/v2.x/en/faq/kubectl/_index.md new file mode 100644 index 00000000000..b4172ab0a40 --- /dev/null +++ b/content/rancher/v2.x/en/faq/kubectl/_index.md @@ -0,0 +1,30 @@ +--- +title: Installing and Configuring kubectl +weight: 100 +--- + +`kubectl` is a CLI utility for running commands against Kubernetes clusters. It's required for many maintenance and administrative tasks in Rancher 2.x. + +### Installation + +See [kubectl Installation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for installation on your operating system. + +### Configuration + +When you create a Kubernetes cluster with RKE, RKE creates a `kube_config_rancher-cluster.yml` in the local directory that contains credentials to connect to your new cluster with tools like `kubectl` or `helm`. + +You can copy this file to `$HOME/.kube/config` or if you are working with multiple Kubernetes clusters, set the `KUBECONFIG` environmental variable to the path of `kube_config_rancher-cluster.yml`. + +``` +export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml +``` + +Test your connectivity with `kubectl` and see if you can get the list of nodes back. + +``` +kubectl get nodes + NAME STATUS ROLES AGE VERSION +165.227.114.63 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.116.167 Ready controlplane,etcd,worker 11m v1.10.1 +165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 +``` diff --git a/content/rancher/v2.x/en/installation/api-auditing/_index.md b/content/rancher/v2.x/en/installation/api-auditing/_index.md new file mode 100644 index 00000000000..e20747d0897 --- /dev/null +++ b/content/rancher/v2.x/en/installation/api-auditing/_index.md @@ -0,0 +1,575 @@ +--- +title: API Auditing +weight: 10000 +--- + +Rancher ships with API Auditing 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. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. + +You can enable API Auditing during Rancher installation or upgrade. + +## API Auditing Usage + +The usage below defines rules about what the audit log should record and what data it should include: + + +Parameter | Description | +---------|----------| + `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value.

See [Audit Level Logging](#audit-level-logging) 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.

Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`
| + `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. + +
+#### Audit Level Logging + +The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#audit-level) setting. + +| `AUDIT_LEVEL` Setting | Request Header | Request Body | Response Header | Response Header | +| --------------------- | ------------------ | ------------ | ------------------- | ------------------- | +| `0` | | | | | +| `1` | ✓ | | | | +| `2` | ✓ | ✓ | | | +| `3` | ✓ | ✓ | ✓ | ✓ | + +## Enabling API Auditing + +To enable API auditing, stop the Docker container that's running Rancher, and then restart it using the following command. This command includes parameters that turns on API auditing. For more information about usage for each switch related to API auditing, see [API Auditing Usage](#api-auditing-usage). + + +``` + docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /root/var/log/auditlog:/var/log/auditlog \ + -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 \ + rancher/rancher:latest +``` + +## Viewing API Audit Logs + +By default, you can view your audit logs on any of your cluster nodes at `root/var/log/auditlog/rancher-api-audit.log` using your favorite text editor. For example: + +``` +less /var/log/auditlog/rancher-api-audit.log +``` + +If you changed the `AUDIT_LOG_PATH` parameter, look in that location for `rancher-api-audit.log` instead. + +## 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" + } + } +} +``` \ No newline at end of file diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index f139cc0b560..619fbae7a62 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -50,7 +50,7 @@ helm install rancher-stable/rancher --name rancher --namespace cattle-system \ #### LetsEncrypt -Use LetsEncrypt's free service to issue trusted SSL certs. This configuration uses http validation so the Load Balancer must have a Public DNS record and be accessible from the internet. +Use [LetsEncrypt](https://letsencrypt.org/)'s free service to issue trusted SSL certs. This configuration uses http validation so the Load Balancer must have a Public DNS record and be accessible from the internet. Set `hostname`, `ingress.tls.source=letEncrypt` and LetsEncrypt options. @@ -61,8 +61,6 @@ helm install rancher-stable/rancher --name rancher --namespace cattle-system \ --set letsEncrypt.email=me@example.org ``` -> LetsEncrypt ProTip: The default `production` environment only allows you to register a name 5 times in a week. If you're rebuilding a bunch of times, use `--set letsEncrypt.environment=staging` until you have you're confident your config is right. - #### Certificates from Files (Kubernetes Secret) Create Kubernetes Secrets from your own certificates for Rancher to use. diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md index ab51ecfc554..bef2d2ab927 100644 --- a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/_index.md @@ -56,7 +56,7 @@ You can copy this file to `$HOME/.kube/config` or if you are working with multip export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml ``` -Test you connectivity with `kubectl` and see if you can get the list of nodes back. +Test your connectivity with `kubectl` and see if you can get the list of nodes back. ``` kubectl get nodes @@ -67,6 +67,33 @@ NAME STATUS ROLES AGE VER 165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1 ``` +### 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-one Jobs. For these pods `READY` should be `0/1`. + +``` +kubectl get pods --all-namespaces + +NAMESPACE NAME READY STATUS RESTARTS AGE +ingress-nginx nginx-ingress-controller-tnsn4 1/1 Running 0 30s +ingress-nginx nginx-ingress-controller-tw2ht 1/1 Running 0 30s +ingress-nginx nginx-ingress-controller-v874b 1/1 Running 0 30s +kube-system canal-jp4hz 3/3 Running 0 30s +kube-system canal-z2hg8 3/3 Running 0 30s +kube-system canal-z6kpw 3/3 Running 0 30s +kube-system kube-dns-7588d5b5f5-sf4vh 3/3 Running 0 30s +kube-system kube-dns-autoscaler-5db9bbb766-jz2k6 1/1 Running 0 30s +kube-system metrics-server-97bc649d5-4rl2q 1/1 Running 0 30s +kube-system rke-ingress-controller-deploy-job-bhzgm 0/1 Completed 0 30s +kube-system rke-kubedns-addon-deploy-job-gl7t4 0/1 Completed 0 30s +kube-system rke-metrics-addon-deploy-job-7ljkc 0/1 Completed 0 30s +kube-system rke-network-plugin-deploy-job-6pbgj 0/1 Completed 0 30s +``` + ### Save your files Save a copy of the `kube_config_rancher-cluster.yml` and `rancher-cluster.yml` files. You will need these files to maintain and upgrade your Rancher instance. diff --git a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md index 6e677bc0f18..bca5815cccd 100644 --- a/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md +++ b/content/rancher/v2.x/en/installation/ha/kubernetes-rke/troubleshooting/_index.md @@ -3,6 +3,16 @@ title: Troubleshooting weight: 276 --- +#### 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 set up SSH tunneling for host [xxx.xxx.xxx.xxx]: Can't retrieve Docker Info ##### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed) diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md index eab29cd6494..845423dcb06 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/_index.md @@ -5,7 +5,7 @@ weight: 276 Rancher can be installed by providing the appropriate Kubernetes manifest configurations to RKE's `addons` feature. See the following instructions for examples appropriate to your environment. -* [High Availability Installation with External Load Balancer (TCP/Layer 4)]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/layer-4-lb/) -* [High Availability Installation with External Load Balancer (HTTPS/Layer 7)]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/layer-7-lb/) -* [HTTP Proxy Configuration for a High Availability Installation]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/proxy/) -* [Troubleshooting RKE Add-on Installs]({{< baseurl >}}/rancher/v2.x/installation/ha/rke-add-on/troubleshooting/) +* [High Availability Installation with External Load Balancer (TCP/Layer 4)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb) +* [High Availability Installation with External Load Balancer (HTTPS/Layer 7)]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb) +* [HTTP Proxy Configuration for a High Availability Installation]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/proxy/) +* [Troubleshooting RKE Add-on Installs]({{< baseurl >}}/rancher/v2.x/en/installation/ha/rke-add-on/troubleshooting/) diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md index 581fa1b6f21..8a6c5c98106 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/_index.md @@ -47,15 +47,19 @@ Installation of Rancher in a high-availability configuration involves multiple p And the **FQDN** part. -9. [Back Up Your RKE Config File](#9-back-up-your-rke-config-file) +9. [Configure Rancher version](#9-configure-rancher-version) + + Configure the **Rancher version** to use. + +10. [Back Up Your RKE Config File](#10-back-up-your-rke-config-file) After you've completed configuration of the RKE config file: 1. it's no longer a template since you'll be using it, and 2. you should back up the RKE config file to a safe place. You will reuse this file for upgrades later. -10. [Run RKE](#10-run-rke) +11. [Run RKE](#11-run-rke) Run RKE to deploy Rancher to your cluster. -11. [Back Up Auto-Generated Config File](#11-back-up-auto-generated-config-file) +12. [Back Up Auto-Generated Config File](#12-back-up-auto-generated-config-file) During installation, RKE generates a config file that you'll use later for upgrades. Back it up to a safe location. @@ -230,6 +234,10 @@ RKE uses a `.yml` config file to install and configure your Kubernetes cluster. - [Template for self-signed certificate
`3-node-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/e9d29b3f3b9673421961c68adf0516807d1317eb/rke-templates/3-node-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-certificate-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/d8ca0805a3958552e84fdf5d743859097ae81e0b/rke-templates/3-node-certificate-recognizedca.yml) + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + 2. Rename the file to `rancher-cluster.yml`. ## 6. Configure Nodes @@ -393,11 +401,23 @@ After replacing `` with the FQDN chosen in [Configure DNS](#3-configure-dn Save the `.yml` file and close it. -## 9. Back Up Your RKE Config File +## 9. Configure Rancher version + +The last reference that needs to be replaced is ``. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](https://github.com/rancher/rancher/blob/master/README.md). Make sure the version is an actual version number, and not a named tag like `stable` or `latest`. The example below shows the version configured to `v2.0.6`. + +``` + spec: + serviceAccountName: cattle-admin + containers: + - image: rancher/rancher:v2.0.6 + imagePullPolicy: Always +``` + +## 10. Back Up Your RKE Config File After you close your `.yml` file, back it up to a secure location. You can use this file again when it's time to upgrade Rancher. -## 10. Run RKE +## 11. Run RKE With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file. @@ -425,7 +445,7 @@ INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1] INFO[0101] Finished building Kubernetes cluster successfully ``` -## 11. Back Up Auto-Generated Config File +## 12. Back Up Auto-Generated Config File During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server. diff --git a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md index a000c8089ea..cbe17e1da7b 100644 --- a/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/rke-add-on/layer-7-lb/_index.md @@ -47,15 +47,19 @@ Installation of Rancher in a high-availability configuration involves multiple p And the **FQDN** part. -9. [Back Up Your RKE Config File](#9-back-up-your-rke-config-file) +9. [Configure Rancher version](#9-configure-rancher-version) + + Configure the **Rancher version** to use. + +10. [Back Up Your RKE Config File](#10-back-up-your-rke-config-file) After you've completed configuration of the RKE config file: 1. it's no longer a template since you'll be using it, and 2. you should back up the RKE config file to a safe place. You will reuse this file for upgrades later. -10. [Run RKE](#10-run-rke) +11. [Run RKE](#11-run-rke) Run RKE to deploy Rancher to your cluster. -11. [Back Up Auto-Generated Config File](#11-back-up-auto-generated-config-file) +12. [Back Up Auto-Generated Config File](#12-back-up-auto-generated-config-file) During installation, RKE generates a config file that you'll use later for upgrades. Back it up to a safe location. @@ -179,6 +183,11 @@ RKE uses a YAML config file to install and configure your Kubernetes cluster. Th - [Template for self-signed certificate
`3-node-externalssl-certificate.yml`](https://raw.githubusercontent.com/rancher/rancher/58e695b51096b1f404188379cea6f6a35aea9e4c/rke-templates/3-node-externalssl-certificate.yml) - [Template for certificate signed by recognized CA
`3-node-externalssl-recognizedca.yml`](https://raw.githubusercontent.com/rancher/rancher/7f60dc3afe1b45287ac36ba6bde6f7c6e35c11fe/rke-templates/3-node-externalssl-recognizedca.yml) + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file. For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + + 2. Rename the file to `rancher-cluster.yml`. ## 6. Configure Nodes @@ -293,11 +302,23 @@ There is one reference to `` in the RKE config file. Replace this referenc 3. Save the file and close it. -## 9. Back Up Your RKE Config File +## 9. Configure Rancher version + +The last reference that needs to be replaced is ``. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](https://github.com/rancher/rancher/blob/master/README.md). Make sure the version is an actual version number, and not a named tag like `stable` or `latest`. The example below shows the version configured to `v2.0.6`. + +``` + spec: + serviceAccountName: cattle-admin + containers: + - image: rancher/rancher:v2.0.6 + imagePullPolicy: Always +``` + +## 10. Back Up Your RKE Config File After you close your RKE config file, `rancher-cluster.yml`, back it up to a secure location. You can use this file again when it's time to upgrade Rancher. -## 10. Run RKE +## 11. Run RKE With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file. @@ -325,7 +346,7 @@ With all configuration in place, use RKE to launch Rancher. You can complete thi INFO[0101] Finished building Kubernetes cluster successfully ``` -## 11. Back Up Auto-Generated Config File +## 12. Back Up Auto-Generated Config File During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the `rancher-cluster.yml` file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server. @@ -333,7 +354,7 @@ During installation, RKE automatically generates a config file named `kube_confi You have a couple of options: -- Create a backup of your Rancher Server in case of a disaster scenario: [High Availablility Back Up and Restoration]({{< baseurl >}}/rancher/v2.x/en/backups/ha-backups/). +- Create a backup of your Rancher Server in case of a disaster scenario: [High Availablility Back Up and Restoration]({{< baseurl >}}/rancher/v2.x/en/backups/backups/ha-backups/). - Create a Kubernetes cluster: [Creating a Cluster]({{< baseurl >}}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/).
diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index dbad2d3808e..47c3d7a2da9 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -52,8 +52,8 @@ The following diagram depicts the basic port requirements for Rancher. For a com 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. ->**Attention Air Gap Users:** -> If you are visiting this page to complete an [Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/) Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. +>**Attention Air Gap Users:** +> If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. > > Example: ``` @@ -68,6 +68,17 @@ Choose from the following options: - [Option D—Bring Your Own Certificate: Private CA Root Certificate CA](#option-d-bring-your-own-certificate-private-ca-root-certificate) - [Option E—Let's Encrypt Certificate](#option-e-let-s-encrypt-certificate) +>**Want records of all transactions with the Rancher API?** +> +>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. +>``` +-e AUDIT_LEVEL=1 \ +-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ +-e AUDIT_LOG_MAXAGE=20 \ +-e AUDIT_LOG_MAXBACKUP=20 \ +-e AUDIT_LOG_MAXSIZE=100 \ +``` + ### Option A—Default Self-Signed Certificate If you install Rancher without using your own certificate, Rancher generates a self-signed certificate that's used for encryption. If you're satisfied with this certificate, there's no need to obtain your own. diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 0340095d70b..44b401e507d 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -60,7 +60,7 @@ The following diagram depicts the basic port requirements for Rancher. For a com 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. >**Attention Air Gap Users:** -> If you are visiting this page to complete [Air Gap Installation](../air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `` with your private registry URL. +> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `` with your private registry URL. > > Example: ``` @@ -70,6 +70,17 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher - [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed) - [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca) +>**Want records of all transactions with the Rancher API?** +> +>Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. +>``` +-e AUDIT_LEVEL=1 \ +-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ +-e AUDIT_LOG_MAXAGE=20 \ +-e AUDIT_LOG_MAXBACKUP=20 \ +-e AUDIT_LOG_MAXSIZE=100 \ +``` + ### Option A-Bring Your Own Certificate: Self-Signed If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the docker command to deploy Rancher, pointing it toward your certificate. diff --git a/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md b/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md index 02745f1d2fc..1945c47315b 100644 --- a/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md +++ b/content/rancher/v2.x/en/upgrades/rollbacks/ha-server-rollbacks/_index.md @@ -6,74 +6,10 @@ aliases: - /rancher/v2.x/en/upgrades/ha-server-rollbacks --- -If you upgrade Rancher, but the upgrade does not complete successfully, you may need to roll back your Rancher Server to its last healthy state before upgrade. To restore Rancher: +If you upgrade Rancher and the upgrade does not complete successfully, you may need to rollback your Rancher Server to its last healthy state. -- Restore the `etcd` snapshot taken before upgrade. -- Run the command to revert to your prior version of Rancher. +To restore Rancher follow the procedure detailed here: [Restoring Backups — High Availability Installs](/rancher/v2.x/en/backups/restorations/ha-restoration) ->**Warning!** -> -> Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur. +Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot. -> ->**Prerequisites:** {{< requirements_rollback >}} - -1. Open **Terminal** and change directory to the location of the RKE binary that you used during upgrade. - -1. Run one of the following commands to restore the `etcd` snapshot [that you took]({{< baseurl >}}/rancher/v2.x/en/upgrades/upgrade-scenarios/ha-server-upgrade/#snapshot) before your unsuccessful upgrade. Replace the `` placeholder with your snapshot. - - ``` - # MacOS - ./rke_darwin-amd64 etcd snapshot-restore --name --config rancher-cluster.yml - # Linux - ./rke_linux-amd64 etcd snapshot-restore --name --config rancher-cluster.yml - ``` - -1. Run one of the following commands to bring your cluster back up: - - ``` - # MacOS - ./rke_darwin-amd64 up --config rancher-cluster.yml - # Linux - ./rke_linux-amd64 up --config rancher-cluster.yml - ``` - -1. Lastly, restart the Kubernetes components on all cluster nodes to prevent potential `etcd` conflicts. Run this command on each of your nodes. - - ``` - docker restart kube-apiserver kubelet kube-controller-manager kube-scheduler kube-proxy - docker ps | grep flannel | cut -f 1 -d " " | xargs docker restart - docker ps | grep calico | cut -f 1 -d " " | xargs docker restart - ``` -1. Enter the following command: - - ``` -kubectl --kubeconfig=kube_config_rancher-cluster.yml set image deployment/cattle cattle-server=rancher/rancher: -n cattle-system - ``` - Replace `` with the version that you were running before upgrade. For a list of tags available, see the [Rancher Forum Announcements](https://forums.rancher.com/c/announcements). - - **Step Result:** The rollback begins. Rancher Server may be unavailable for a few minutes. - -1. Log into Rancher. Confirm that the rollback succeeded by checking the version displayed in the bottom-left corner of the browser window. - -## Troubleshooting - -With **RKE v0.1.8** and below, the **rke-bundle-cert** container is left over from a failed etcd restore. If you are having an issue with restoring an **etcd snapshot** then you can do the following on each etcd nodes before attempting to do another restore: - -``` -docker container rm --force rke-bundle-cert -``` - -The rke-bundle-cert container is usually removed when a backup or restore of **etcd** succeeds. -Whenever something goes wrong, the **rke-bundle-cert** container will be left over. You can look -at the logs or inspect the container to see what the issue is. - -``` -docker container logs --follow rke-bundle-cert -docker container inspect rke-bundle-cert -``` - -The important thing to note is the mounts of the container and location of the **pki.bundle.tar.gz**. - -As of **RKE v0.1.9**, the **rke-bundle-cert** container is removed on both success and -failure of a restore. To debug any issues, you will need to look at the **logs** generated from rke. +> **NOTE:** Managed cluster are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken. diff --git a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md index 0e699a7a9df..416ada0d3a3 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/ha-server-upgrade/_index.md @@ -17,6 +17,10 @@ To upgrade Rancher 2.x running in a high availability configuration, run an upgr 1. Change directory to the location of the RKE binary. Your `rancher-cluster.yml` file must reside in the same directory. + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by editing your RKE config file (`rancher-cluster.yml`). For more information, see [RKE Documentation: API Auditing]({{< baseurl >}}\rke\v0.1.x\en\config-options\add-ons\api-auditing). + 1. Enter the following command. Replace `` with any name that you want to use for the snapshot (e.g. `upgrade.db`). ``` diff --git a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md index 6247147afa8..80d9f0c4db2 100644 --- a/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md +++ b/content/rancher/v2.x/en/upgrades/upgrades/single-node-upgrade/_index.md @@ -55,6 +55,18 @@ docker pull rancher/rancher:latest docker run -d --volumes-from rancher-data --restart=unless-stopped \ -p 80:80 -p 443:443 rancher/rancher:latest ``` + + >**Want records of all transactions with the Rancher API?** + > + >Enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your upgrade 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 \ + ``` + >**Note:** _Do not_ stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades. >
>
diff --git a/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md b/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md new file mode 100644 index 00000000000..6b4e72ff36b --- /dev/null +++ b/content/rke/v0.1.x/en/config-options/add-ons/api-auditing/_index.md @@ -0,0 +1,47 @@ +--- +title: API Auditing +weight: 10000 +--- + +If you're using RKE to install Rancher, you can use directives to enable API Auditing for your Rancher install. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use. + +## In-line Arguments + +Enable API Auditing using RKE by adding arguments to your Rancher container. + +To enable API auditing: + +- Add API Auditing arguments (`args`) to your Rancher container. +- Declare a `mountPath` in the `volumeMounts` directive of the container. +- Declare a `path` in the `volumes` directive. + +For more information about each argument, its syntax, and how to view API Audit logs, see [Rancher v2.0 Documentation: API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing). + +```yaml +... +containers: + - image: rancher/rancher:latest + imagePullPolicy: Always + name: cattle-server + args: ["--audit-log-path", "/var/log/auditlog/rancher-api-audit.log", "--audit-log-maxbackup", "5", "--audit-log-maxsize", "50", "--audit-level", "2"] + ports: + - containerPort: 80 + protocol: TCP + - containerPort: 443 + protocol: TCP + volumeMounts: + - mountPath: /etc/rancher/ssl + name: cattle-keys-volume + readOnly: true + - mountPath: /var/log/auditlog + name: audit-log-dir + volumes: + - name: cattle-keys-volume + secret: + defaultMode: 420 + secretName: cattle-keys-server + - name: audit-log-dir + hostPath: + path: /var/log/rancher/auditlog + type: Directory +```