mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 20:48:11 +00:00
Move version-2.0-2.4 to new arhived directory and don't publish. Remove sidebar entries and add 'Archived' to labels
This commit is contained in:
Billy Tat
@@ -1,140 +0,0 @@
|
||||
---
|
||||
title: Contributing to Rancher
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/contribute-to-rancher"/>
|
||||
</head>
|
||||
|
||||
Learn about the repositories used for Rancher and Rancher docs, how to build Rancher repositories, and what information to include when you file an issue.
|
||||
|
||||
For more detailed information on how to contribute to the development of Rancher projects, refer to the [Rancher Developer Wiki](https://github.com/rancher/rancher/wiki). The wiki has resources on many topics, including the following:
|
||||
|
||||
- How to set up the Rancher development environment and run tests
|
||||
- The typical flow of an issue through the development lifecycle
|
||||
- Coding guidelines and development best practices
|
||||
- Debugging and troubleshooting
|
||||
- Developing the Rancher API
|
||||
|
||||
On the Rancher Users Slack, the channel for developers is **#developer**.
|
||||
|
||||
## Rancher Docs
|
||||
|
||||
If you have suggestions for the documentation on this website, [open](https://github.com/rancher/rancher-docs/issues/new/choose) an issue in the main [Rancher docs](https://github.com/rancher/rancher-docs) repository. This repo contains documentation for Rancher v2.0 and later.
|
||||
|
||||
See the [Rancher docs README](https://github.com/rancher/rancher-docs#readme) for more details on contributing to and building the Rancher v2.x docs repo.
|
||||
|
||||
For documentation describing Rancher v1.6 and earlier, see the [Rancher 1.x docs](https://github.com/rancher/rancher.github.io) repo, which contains source files for https://rancher.com/docs/rancher/v1.6/en/.
|
||||
|
||||
## Rancher Repositories
|
||||
|
||||
All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher.
|
||||
|
||||
Repository | URL | Description
|
||||
-----------|-----|-------------
|
||||
Rancher | https://github.com/rancher/rancher | This repository is the main source code for Rancher 2.x.
|
||||
Types | https://github.com/rancher/types | This repository is the repository that has all the API types for Rancher 2.x.
|
||||
API Framework | https://github.com/rancher/norman | This repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources.
|
||||
User Interface | https://github.com/rancher/dashboard/ | This repository is the source of the Dashboard UI.
|
||||
(Rancher) Docker Machine | https://github.com/rancher/machine | This repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the `docker/machine` repository.
|
||||
machine-package | https://github.com/rancher/machine-package | This repository is used to build the Rancher Docker Machine binary.
|
||||
kontainer-engine | https://github.com/rancher/kontainer-engine | This repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters.
|
||||
RKE repository | https://github.com/rancher/rke | This repository is the source of Rancher Kubernetes Engine, the tool to provision Kubernetes clusters on any machine.
|
||||
CLI | https://github.com/rancher/cli | This repository is the source code for the Rancher CLI used in Rancher 2.x.
|
||||
(Rancher) Helm repository | https://github.com/rancher/helm | This repository is the source of the packaged Helm binary. This is a fork of the `helm/helm` repository.
|
||||
Telemetry repository | https://github.com/rancher/telemetry | This repository is the source for the Telemetry binary.
|
||||
loglevel repository | https://github.com/rancher/loglevel | This repository is the source of the loglevel binary, used to dynamically change log levels.
|
||||
|
||||
To see all libraries/projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository.
|
||||
|
||||
<br/>
|
||||
<sup>Rancher components used for provisioning/managing Kubernetes clusters.</sup>
|
||||
|
||||
### Building Rancher Repositories
|
||||
|
||||
Every repository should have a Makefile and can be built using the `make` command. The `make` targets are based on the scripts in the `/scripts` directory in the repository, and each target will use [Dapper](https://github.com/rancher/dapper) to run the target in an isolated environment. The `Dockerfile.dapper` will be used for this process, and includes all the necessary build tooling needed.
|
||||
|
||||
The default target is `ci`, and will run `./scripts/validate`, `./scripts/build`, `./scripts/test` and `./scripts/package`. The resulting binaries of the build will be in `./build/bin` and are usually also packaged in a Docker image.
|
||||
|
||||
### Rancher Bugs, Issues or Questions
|
||||
|
||||
If you find any bugs or are having any trouble, please search the [reported issue](https://github.com/rancher/rancher/issues) as someone may have experienced the same issue or we are actively working on a solution.
|
||||
|
||||
If you can't find anything related to your issue, contact us by [filing an issue](https://github.com/rancher/rancher/issues/new). Though we have many repositories related to Rancher, we want the bugs filed in the Rancher repository so we won't miss them! If you want to ask a question or ask fellow users about an use case, we suggest creating a post on the [Rancher Forums](https://forums.rancher.com).
|
||||
|
||||
#### Checklist for Filing Issues
|
||||
|
||||
Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue.
|
||||
|
||||
:::note
|
||||
|
||||
For large amounts of data, please use [GitHub Gist](https://gist.github.com/) or similar and link the created resource in the issue.
|
||||
|
||||
:::
|
||||
|
||||
:::note Important:
|
||||
|
||||
Please remove any sensitive data as it will be publicly viewable.
|
||||
|
||||
:::
|
||||
|
||||
- **Resources:** Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below:
|
||||
- **Hosts:** What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce
|
||||
- **Operating System:** What operating system are you using? Providing specifics helps here like the output of `cat /etc/os-release` for exact OS release and `uname -r` for exact kernel used
|
||||
- **Docker:** What Docker version are you using, how did you install it? Most of the details of Docker can be found by supplying output of `docker version` and `docker info`
|
||||
- **Environment:** Are you in a proxy environment, are you using recognized CA/self signed certificates, are you using an external loadbalancer
|
||||
- **Rancher:** What version of Rancher are you using, this can be found on the bottom left of the UI or be retrieved from the image tag you are running on the host
|
||||
- **Clusters:** What kind of cluster did you create, how did you create it, what did you specify when you were creating it
|
||||
- **Steps to reproduce the issue:** Provide as much detail on how you got into the reported situation. This helps the person to reproduce the situation you are in.
|
||||
- Provide manual steps or automation scripts used to get from a newly created setup to the situation you reported.
|
||||
- **Logs:** Provide data/logs from the used resources.
|
||||
- Rancher
|
||||
- Docker install
|
||||
|
||||
```
|
||||
docker logs \
|
||||
--timestamps \
|
||||
$(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }')
|
||||
```
|
||||
- Kubernetes install using `kubectl`
|
||||
|
||||
:::note
|
||||
|
||||
Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.
|
||||
|
||||
:::
|
||||
|
||||
```
|
||||
kubectl -n cattle-system \
|
||||
logs \
|
||||
-l app=rancher \
|
||||
--timestamps=true
|
||||
```
|
||||
- Docker install using `docker` on each of the nodes in the RKE cluster
|
||||
|
||||
```
|
||||
docker logs \
|
||||
--timestamps \
|
||||
$(docker ps | grep -E "rancher/rancher@|rancher_rancher" | awk '{ print $1 }')
|
||||
```
|
||||
- Kubernetes Install with RKE Add-On
|
||||
|
||||
:::note
|
||||
|
||||
Make sure you configured the correct kubeconfig (for example, `export KUBECONFIG=$PWD/kube_config_cluster.yml` if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.
|
||||
|
||||
:::
|
||||
|
||||
```
|
||||
kubectl -n cattle-system \
|
||||
logs \
|
||||
--timestamps=true \
|
||||
-f $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name="cattle-server") | .metadata.name')
|
||||
```
|
||||
- System logging (these might not all exist, depending on operating system)
|
||||
- `/var/log/messages`
|
||||
- `/var/log/syslog`
|
||||
- `/var/log/kern.log`
|
||||
- Docker daemon logging (these might not all exist, depending on operating system)
|
||||
- `/var/log/docker.log`
|
||||
- **Metrics:** If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of `top`, `free -m`, `df` which shows processes/memory/disk usage.
|
||||
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: Explanations
|
||||
---
|
||||
|
||||
**Explanatory docs** are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.
|
||||
-26
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: CIS Scans
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/cis-scans"/>
|
||||
</head>
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [How-to Guides](#how-to-guides)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To run security scans on a cluster and access the generated reports, you must be an [Administrator](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [Cluster Owner.](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
|
||||
|
||||
Rancher can only run security scans on clusters that were created with RKE, which includes custom clusters and clusters that Rancher created in an infrastructure provider such as Amazon EC2 or GCE. Imported clusters and clusters in hosted Kubernetes providers can't be scanned by Rancher.
|
||||
|
||||
The security scan cannot run in a cluster that has Windows nodes.
|
||||
|
||||
You will only be able to see the CIS scan reports for clusters that you have access to.
|
||||
|
||||
## How-to Guides
|
||||
|
||||
Please refer [here](../../../how-to-guides/advanced-user-guides/cis-scan-guides/cis-scan-guides.md) for how-to guides on CIS scans.
|
||||
-106
@@ -1,106 +0,0 @@
|
||||
---
|
||||
title: Skipped and Not Applicable Tests
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests"/>
|
||||
</head>
|
||||
|
||||
This section lists the tests that are skipped in the permissive test profile for RKE.
|
||||
|
||||
All the tests that are skipped and not applicable on this page will be counted as Not Applicable in the generated report. The skipped test count will only mention the user-defined skipped tests. This allows user-skipped tests to be distinguished from the tests that are skipped by default in the RKE permissive test profile.
|
||||
|
||||
|
||||
## CIS Benchmark v1.5
|
||||
|
||||
### CIS Benchmark v1.5 Skipped Tests
|
||||
|
||||
| Number | Description | Reason for Skipping |
|
||||
| ---------- | ------------- | --------- |
|
||||
| 1.1.12 | Ensure that the etcd data directory ownership is set to etcd:etcd (Scored) | A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership. |
|
||||
| 1.2.6 | Ensure that the --kubelet-certificate-authority argument is set as appropriate (Scored) | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. |
|
||||
| 1.2.16 | Ensure that the admission control plugin PodSecurityPolicy is set (Scored) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 1.2.33 | Ensure that the --encryption-provider-config argument is set as appropriate (Not Scored) | Enabling encryption changes how data can be recovered as data is encrypted. |
|
||||
| 1.2.34 | Ensure that encryption providers are appropriately configured (Not Scored) | Enabling encryption changes how data can be recovered as data is encrypted. |
|
||||
| 4.2.6 | Ensure that the --protect-kernel-defaults argument is set to true (Scored) | System level configurations are required before provisioning the cluster in order for this argument to be set to true. |
|
||||
| 4.2.10 | Ensure that the--tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored) | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers. |
|
||||
| 5.1.5 | Ensure that default service accounts are not actively used. (Scored) | Kubernetes provides default service accounts to be used. |
|
||||
| 5.2.2 | Minimize the admission of containers wishing to share the host process ID namespace (Scored) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.3 | Minimize the admission of containers wishing to share the host IPC namespace (Scored) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.4 | Minimize the admission of containers wishing to share the host network namespace (Scored) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.2.5 | Minimize the admission of containers with allowPrivilegeEscalation (Scored) | Enabling Pod Security Policy can cause applications to unexpectedly fail. |
|
||||
| 5.3.2 | Ensure that all Namespaces have Network Policies defined (Scored) | Enabling Network Policies can prevent certain applications from communicating with each other. |
|
||||
| 5.6.4 | The default namespace should not be used (Scored) | Kubernetes provides a default namespace. |
|
||||
|
||||
### CIS Benchmark v1.5 Not Applicable Tests
|
||||
|
||||
| Number | Description | Reason for being not applicable |
|
||||
| ---------- | ------------- | --------- |
|
||||
| 1.1.1 | Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.2 | Ensure that the API server pod specification file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.3 | Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.4 | Ensure that the controller manager pod specification file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.5 | Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.6 | Ensure that the scheduler pod specification file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.7 | Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.8 | Ensure that the etcd pod specification file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.13 | Ensure that the admin.conf file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes. |
|
||||
| 1.1.14 | Ensure that the admin.conf file ownership is set to root:root (Scored) | Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes. |
|
||||
| 1.1.15 | Ensure that the scheduler.conf file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.16 | Ensure that the scheduler.conf file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.17 | Ensure that the controller-manager.conf file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.1.18 | Ensure that the controller-manager.conf file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time. |
|
||||
| 1.3.6 | Ensure that the RotateKubeletServerCertificate argument is set to true (Scored) | Clusters provisioned by RKE handles certificate rotation directly through RKE. |
|
||||
| 4.1.1 | Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.2 | Ensure that the kubelet service file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.9 | Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Scored) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time. |
|
||||
| 4.1.10 | Ensure that the kubelet configuration file ownership is set to root:root (Scored) | Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time. |
|
||||
| 4.2.12 | Ensure that the RotateKubeletServerCertificate argument is set to true (Scored) | Clusters provisioned by RKE handles certificate rotation directly through RKE. |
|
||||
|
||||
## CIS Benchmark v1.4
|
||||
|
||||
The skipped and not applicable tests for CIS Benchmark v1.4 are as follows:
|
||||
|
||||
### CIS Benchmark v1.4 Skipped Tests
|
||||
|
||||
Number | Description | Reason for Skipping
|
||||
---|---|---
|
||||
1.1.11 | "Ensure that the admission control plugin AlwaysPullImages is set (Scored)" | Enabling AlwaysPullImages can use significant bandwidth.
|
||||
1.1.21 | "Ensure that the --kubelet-certificate-authority argument is set as appropriate (Scored)" | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
|
||||
1.1.24 | "Ensure that the admission control plugin PodSecurityPolicy is set (Scored)" | Enabling Pod Security Policy can cause applications to unexpectedly fail.
|
||||
1.1.34 | "Ensure that the --encryption-provider-config argument is set as appropriate (Scored)" | Enabling encryption changes how data can be recovered as data is encrypted.
|
||||
1.1.35 | "Ensure that the encryption provider is set to aescbc (Scored)" | Enabling encryption changes how data can be recovered as data is encrypted.
|
||||
1.1.36 | "Ensure that the admission control plugin EventRateLimit is set (Scored)" | EventRateLimit needs to be tuned depending on the cluster.
|
||||
1.2.2 | "Ensure that the --address argument is set to 127.0.0.1 (Scored)" | Adding this argument prevents Rancher's monitoring tool to collect metrics on the scheduler.
|
||||
1.3.7 | "Ensure that the --address argument is set to 127.0.0.1 (Scored)" | Adding this argument prevents Rancher's monitoring tool to collect metrics on the controller manager.
|
||||
1.4.12 | "Ensure that the etcd data directory ownership is set to etcd:etcd (Scored)" | A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership.
|
||||
1.7.2 | "Do not admit containers wishing to share the host process ID namespace (Scored)" | Enabling Pod Security Policy can cause applications to unexpectedly fail.
|
||||
1.7.3 | "Do not admit containers wishing to share the host IPC namespace (Scored)" | Enabling Pod Security Policy can cause applications to unexpectedly fail.
|
||||
1.7.4 | "Do not admit containers wishing to share the host network namespace (Scored)" | Enabling Pod Security Policy can cause applications to unexpectedly fail.
|
||||
1.7.5 | " Do not admit containers with allowPrivilegeEscalation (Scored)" | Enabling Pod Security Policy can cause applications to unexpectedly fail.
|
||||
2.1.6 | "Ensure that the --protect-kernel-defaults argument is set to true (Scored)" | System level configurations are required before provisioning the cluster in order for this argument to be set to true.
|
||||
2.1.10 | "Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)" | When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
|
||||
|
||||
### CIS Benchmark v1.4 Not Applicable Tests
|
||||
|
||||
Number | Description | Reason for being not applicable
|
||||
---|---|---
|
||||
1.1.9 | "Ensure that the --repair-malformed-updates argument is set to false (Scored)" | The argument --repair-malformed-updates has been removed as of Kubernetes version 1.14
|
||||
1.3.6 | "Ensure that the RotateKubeletServerCertificate argument is set to true" | Cluster provisioned by RKE handles certificate rotation directly through RKE.
|
||||
1.4.1 | "Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver.
|
||||
1.4.2 | "Ensure that the API server pod specification file ownership is set to root:root (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver.
|
||||
1.4.3 | "Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for controller-manager.
|
||||
1.4.4 | "Ensure that the controller manager pod specification file ownership is set to root:root (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for controller-manager.
|
||||
1.4.5 | "Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for scheduler.
|
||||
1.4.6 | "Ensure that the scheduler pod specification file ownership is set to root:root (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for scheduler.
|
||||
1.4.7 | "Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for etcd.
|
||||
1.4.8 | "Ensure that the etcd pod specification file ownership is set to root:root (Scored)" | Cluster provisioned by RKE doesn't require or maintain a configuration file for etcd.
|
||||
1.4.13 | "Ensure that the admin.conf file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
|
||||
1.4.14 | "Ensure that the admin.conf file ownership is set to root:root (Scored)" | Cluster provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
|
||||
2.1.8 | "Ensure that the --hostname-override argument is not set (Scored)" | Clusters provisioned by RKE clusters and most cloud providers require hostnames.
|
||||
2.1.12 | "Ensure that the --rotate-certificates argument is not set to false (Scored)" | Cluster provisioned by RKE handles certificate rotation directly through RKE.
|
||||
2.1.13 | "Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)" | Cluster provisioned by RKE handles certificate rotation directly through RKE.
|
||||
2.2.3 | "Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)" | Cluster provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service.
|
||||
2.2.4 | "Ensure that the kubelet service file ownership is set to root:root (Scored)" | Cluster provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service.
|
||||
2.2.9 | "Ensure that the kubelet configuration file ownership is set to root:root (Scored)" | RKE doesn’t require or maintain a configuration file for the kubelet.
|
||||
2.2.10 | "Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Scored)" | RKE doesn’t require or maintain a configuration file for the kubelet.
|
||||
-328
@@ -1,328 +0,0 @@
|
||||
---
|
||||
title: Cluster Alerts
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/monitoring-and-alerting"/>
|
||||
</head>
|
||||
|
||||
To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. When an event occurs, your alert is triggered, and you are sent a notification. You can then, if necessary, follow up with corrective actions.
|
||||
|
||||
|
||||
## About Alerts
|
||||
|
||||
Notifiers and alerts are built on top of the [Prometheus Alertmanager](https://prometheus.io/docs/alerting/alertmanager/). Leveraging these tools, Rancher can notify [cluster owners](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) and [project owners](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) of events they need to address.
|
||||
|
||||
Before you can receive alerts, you must configure one or more notifier in Rancher.
|
||||
|
||||
When you create a cluster, some alert rules are predefined. You can receive these alerts if you configure a [notifier](../notifiers.md) for them.
|
||||
|
||||
For details about what triggers the predefined alerts, refer to the [documentation on default alerts.](default-alerts.md)
|
||||
|
||||
### Alert Event Examples
|
||||
|
||||
Some examples of alert events are:
|
||||
|
||||
- A Kubernetes master component entering an unhealthy state.
|
||||
- A node or workload error occurring.
|
||||
- A scheduled deployment taking place as planned.
|
||||
- A node's hardware resources becoming overstressed.
|
||||
|
||||
### Alerts Triggered by Prometheus Queries
|
||||
|
||||
When you edit an alert rule, you will have the opportunity to configure the alert to be triggered based on a Prometheus expression. For examples of expressions, refer to [this page.](../cluster-monitoring/expression.md)
|
||||
|
||||
Monitoring must be [enabled](../cluster-monitoring/cluster-monitoring.md) before you can trigger alerts with custom Prometheus queries or expressions.
|
||||
|
||||
### Urgency Levels
|
||||
|
||||
You can set an urgency level for each alert. This urgency appears in the notification you receive, helping you to prioritize your response actions. For example, if you have an alert configured to inform you of a routine deployment, no action is required. These alerts can be assigned a low priority level. However, if a deployment fails, it can critically impact your organization, and you need to react quickly. Assign these alerts a high priority level.
|
||||
|
||||
### Scope of Alerts
|
||||
|
||||
The scope for alerts can be set at either the cluster level or [project level](../../../reference-guides/rancher-project-tools/project-alerts.md).
|
||||
|
||||
At the cluster level, Rancher monitors components in your Kubernetes cluster, and sends you alerts related to:
|
||||
|
||||
- The state of your nodes.
|
||||
- The system services that manage your Kubernetes cluster.
|
||||
- The resource events from specific system services.
|
||||
- The Prometheus expression cross the thresholds
|
||||
|
||||
### Managing Cluster Alerts
|
||||
|
||||
After you set up cluster alerts, you can manage each alert object. To manage alerts, browse to the cluster containing the alerts, and then select **Tools > Alerts** that you want to manage. You can:
|
||||
|
||||
- Deactivate/Reactive alerts
|
||||
- Edit alert settings
|
||||
- Delete unnecessary alerts
|
||||
- Mute firing alerts
|
||||
- Unmute muted alerts
|
||||
|
||||
## Adding Cluster Alerts
|
||||
|
||||
As a [cluster owner](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to send you alerts for cluster events.
|
||||
|
||||
>**Prerequisite:** Before you can receive cluster alerts, you must [add a notifier](../notifiers.md).
|
||||
|
||||
1. From the **Global** view, navigate to the cluster that you want to configure cluster alerts for. Select **Tools > Alerts**. Then click **Add Alert Group**.
|
||||
1. Enter a **Name** for the alert that describes its purpose, you could group alert rules for the different purpose.
|
||||
1. Based on the type of alert you want to create, refer to the [cluster alert configuration section.](#cluster-alert-configuration)
|
||||
1. Continue adding more **Alert Rule** to the group.
|
||||
1. Finally, choose the [notifiers](../notifiers.md) to send the alerts to.
|
||||
|
||||
- You can set up multiple notifiers.
|
||||
- You can change notifier recipients on the fly.
|
||||
1. Click **Create.**
|
||||
|
||||
**Result:** Your alert is configured. A notification is sent when the alert is triggered.
|
||||
|
||||
|
||||
## Cluster Alert Configuration
|
||||
|
||||
- [System Service Alerts](#system-service-alerts)
|
||||
- [Resource Event Alerts](#resource-event-alerts)
|
||||
- [Node Alerts](#node-alerts)
|
||||
- [Node Selector Alerts](#node-selector-alerts)
|
||||
- [CIS Scan Alerts](#cis-scan-alerts)
|
||||
- [Metric Expression Alerts](#metric-expression-alerts)
|
||||
|
||||
## System Service Alerts
|
||||
|
||||
This alert type monitor for events that affect one of the Kubernetes master components, regardless of the node it occurs on.
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Select the **System Services** option, and then select an option from the dropdown:
|
||||
|
||||
- [controller-manager](https://kubernetes.io/docs/concepts/overview/components/#kube-controller-manager)
|
||||
- [etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd)
|
||||
- [scheduler](https://kubernetes.io/docs/concepts/overview/components/#kube-scheduler)
|
||||
|
||||
### Is
|
||||
|
||||
The alert will be triggered when the selected Kubernetes master component is unhealthy.
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert. The options are:
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level based on the importance of the service and how many nodes fill the role within your cluster. For example, if you're making an alert for the `etcd` service, select **Critical**. If you're making an alert for redundant schedulers, **Warning** is more appropriate.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
|
||||
## Resource Event Alerts
|
||||
|
||||
This alert type monitors for specific events that are thrown from a resource type.
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Choose the type of resource event that triggers an alert. The options are:
|
||||
|
||||
- **Normal**: triggers an alert when any standard resource event occurs.
|
||||
- **Warning**: triggers an alert when unexpected resource events occur.
|
||||
|
||||
Select a resource type from the **Choose a Resource** drop-down that you want to trigger an alert.
|
||||
|
||||
- [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/)
|
||||
- [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
|
||||
- [Node](https://kubernetes.io/docs/concepts/architecture/nodes/)
|
||||
- [Pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/)
|
||||
- [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert.
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level of the alert by considering factors such as how often the event occurs or its importance. For example:
|
||||
|
||||
- If you set a normal alert for pods, you're likely to receive alerts often, and individual pods usually self-heal, so select an urgency of **Info**.
|
||||
- If you set a warning alert for StatefulSets, it's very likely to impact operations, so select an urgency of **Critical**.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
|
||||
## Node Alerts
|
||||
|
||||
This alert type monitors for events that occur on a specific node.
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Select the **Node** option, and then make a selection from the **Choose a Node** drop-down.
|
||||
|
||||
### Is
|
||||
|
||||
Choose an event to trigger the alert.
|
||||
|
||||
- **Not Ready**: Sends you an alert when the node is unresponsive.
|
||||
- **CPU usage over**: Sends you an alert when the node raises above an entered percentage of its processing allocation.
|
||||
- **Mem usage over**: Sends you an alert when the node raises above an entered percentage of its memory allocation.
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert.
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of **Info**, but a node that is **Not Ready** deems an urgency of **Critical**.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
|
||||
## Node Selector Alerts
|
||||
|
||||
This alert type monitors for events that occur on any node on marked with a label. For more information, see the Kubernetes documentation for [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Select the **Node Selector** option, and then click **Add Selector** to enter a key value pair for a label. This label should be applied to one or more of your nodes. Add as many selectors as you'd like.
|
||||
|
||||
### Is
|
||||
|
||||
Choose an event to trigger the alert.
|
||||
|
||||
- **Not Ready**: Sends you an alert when selected nodes are unresponsive.
|
||||
- **CPU usage over**: Sends you an alert when selected nodes raise above an entered percentage of processing allocation.
|
||||
- **Mem usage over**: Sends you an alert when selected nodes raise above an entered percentage of memory allocation.
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert.
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of **Info**, but a node that is **Not Ready** deems an urgency of **Critical**.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
|
||||
## CIS Scan Alerts
|
||||
_Available as of v2.4.0_
|
||||
|
||||
This alert type is triggered based on the results of a CIS scan.
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Select **CIS Scan.**
|
||||
|
||||
### Is
|
||||
|
||||
Choose an event to trigger the alert:
|
||||
|
||||
- Completed Scan
|
||||
- Has Failure
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert.
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of **Info**, but a node that is **Not Ready** deems an urgency of **Critical**.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
|
||||
## Metric Expression Alerts
|
||||
|
||||
This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring.
|
||||
|
||||
Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.
|
||||
|
||||
### When a
|
||||
|
||||
Input or select an **Expression**, the dropdown shows the original metrics from Prometheus, including:
|
||||
|
||||
- [**Node**](https://github.com/prometheus/node_exporter)
|
||||
- [**Container**](https://github.com/google/cadvisor)
|
||||
- [**ETCD**](https://etcd.io/docs/v3.3/op-guide/monitoring/)
|
||||
- [**Kubernetes Components**](https://github.com/kubernetes/metrics)
|
||||
- [**Kubernetes Resources**](https://github.com/kubernetes/kube-state-metrics)
|
||||
- [**Fluentd**](https://docs.fluentd.org/v1.0/articles/monitoring-prometheus) (supported by [Logging](../cluster-logging/cluster-logging.md))
|
||||
- [**Cluster Level Grafana**](https://grafana.com/docs/grafana/latest/setup-grafana/set-up-grafana-monitoring/)
|
||||
- **Cluster Level Prometheus**
|
||||
|
||||
### Is
|
||||
|
||||
Choose a comparison:
|
||||
|
||||
- **Equal**: Trigger alert when expression value equal to the threshold.
|
||||
- **Not Equal**: Trigger alert when expression value not equal to the threshold.
|
||||
- **Greater Than**: Trigger alert when expression value greater than to threshold.
|
||||
- **Less Than**: Trigger alert when expression value equal or less than the threshold.
|
||||
- **Greater or Equal**: Trigger alert when expression value greater to equal to the threshold.
|
||||
- **Less or Equal**: Trigger alert when expression value less or equal to the threshold.
|
||||
|
||||
If applicable, choose a comparison value or a threshold for the alert to be triggered.
|
||||
|
||||
### For
|
||||
|
||||
Select a duration for a trigger alert when the expression value crosses the threshold longer than the configured duration.
|
||||
|
||||
### Send a
|
||||
|
||||
Select the urgency level of the alert.
|
||||
|
||||
- **Critical**: Most urgent
|
||||
- **Warning**: Normal urgency
|
||||
- **Info**: Least urgent
|
||||
|
||||
Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's load expression ```sum(node_load5) / count(node_cpu_seconds_total{mode="system"})``` raises above 0.6 deems an urgency of **Info**, but 1 deems an urgency of **Critical**.
|
||||
|
||||
### Advanced Options
|
||||
|
||||
By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.
|
||||
|
||||
- **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
|
||||
- **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
|
||||
- **Repeat Wait Time**: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
|
||||
-56
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: Default Alerts for Cluster Monitoring
|
||||
---
|
||||
|
||||
When you create a cluster, some alert rules are predefined. These alerts notify you about signs that the cluster could be unhealthy. You can receive these alerts if you configure a [notifier](../notifiers.md) for them.
|
||||
|
||||
Several of the alerts use Prometheus expressions as the metric that triggers the alert. For more information on how expressions work, you can refer to the Rancher [documentation about Prometheus expressions](../cluster-monitoring/expression.md) or the Prometheus [documentation about querying metrics](https://prometheus.io/docs/prometheus/latest/querying/basics/).
|
||||
|
||||
## Alerts for etcd
|
||||
|
||||
Etcd is the key-value store that contains the state of the Kubernetes cluster. Rancher provides default alerts if the built-in monitoring detects a potential problem with etcd. You don't have to enable monitoring to receive these alerts.
|
||||
|
||||
A leader is the node that handles all client requests that need cluster consensus. For more information, you can refer to this [explanation of how etcd works.](https://www.rancher.cn/blog/2019/2019-01-29-what-is-etcd/#how-does-etcd-work)
|
||||
|
||||
The leader of the cluster can change in response to certain events. It is normal for the leader to change, but too many changes can indicate a problem with the network or a high CPU load. With longer latencies, the default etcd configuration may cause frequent heartbeat timeouts, which trigger a new leader election.
|
||||
|
||||
| Alert | Explanation |
|
||||
|-------|-------------|
|
||||
| A high number of leader changes within the etcd cluster are happening | A warning alert is triggered when the leader changes more than three times in one hour. |
|
||||
| Database usage close to the quota 500M | A warning alert is triggered when the size of etcd exceeds 500M.|
|
||||
| Etcd is unavailable | A critical alert is triggered when etcd becomes unavailable. |
|
||||
| Etcd member has no leader | A critical alert is triggered when the etcd cluster does not have a leader for at least three minutes. |
|
||||
|
||||
## Alerts for Kubernetes Components
|
||||
Rancher provides alerts when core Kubernetes system components become unhealthy.
|
||||
|
||||
Controllers update Kubernetes resources based on changes in etcd. The [controller manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) monitors the cluster desired state through the Kubernetes API server and makes the necessary changes to the current state to reach the desired state.
|
||||
|
||||
The [scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/) service is a core component of Kubernetes. It is responsible for scheduling cluster workloads to nodes, based on various configurations, metrics, resource requirements and workload-specific requirements.
|
||||
|
||||
| Alert | Explanation |
|
||||
|-------|-------------|
|
||||
| Controller Manager is unavailable | A critical warning is triggered when the cluster’s controller-manager becomes unavailable. |
|
||||
| Scheduler is unavailable | A critical warning is triggered when the cluster’s scheduler becomes unavailable. |
|
||||
|
||||
## Alerts for Events
|
||||
|
||||
Kubernetes events are objects that provide insight into what is happening inside a cluster, such as what decisions were made by the scheduler or why some pods were evicted from the node. In the Rancher UI, from the project view, you can see events for each workload.
|
||||
|
||||
| Alert | Explanation |
|
||||
|-------|-------------|
|
||||
| Get warning deployment event | A warning alert is triggered when a warning event happens on a deployment. |
|
||||
|
||||
## Alerts for Nodes
|
||||
|
||||
Alerts can be triggered based on node metrics. Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines.
|
||||
|
||||
| Alert | Explanation |
|
||||
|-------|-------------|
|
||||
| High CPU load | A warning alert is triggered if the node uses more than 100 percent of the node’s available CPU seconds for at least three minutes. |
|
||||
| High node memory utilization | A warning alert is triggered if the node uses more than 80 percent of its available memory for at least three minutes. |
|
||||
| Node disk is running full within 24 hours | A critical alert is triggered if the disk space on the node is expected to run out in the next 24 hours based on the disk growth over the last 6 hours. |
|
||||
|
||||
## Project-level Alerts
|
||||
|
||||
When you enable monitoring for the project, some project-level alerts are provided. For details, refer to the [section on project-level alerts.](../../../reference-guides/rancher-project-tools/project-alerts.md)
|
||||
-115
@@ -1,115 +0,0 @@
|
||||
---
|
||||
title: Cluster Logging
|
||||
description: Rancher integrates with popular logging services. Learn the requirements and benefits of integrating with logging services, and enable logging on your cluster.
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/logging"/>
|
||||
</head>
|
||||
|
||||
Logging is helpful because it allows you to:
|
||||
|
||||
- Capture and analyze the state of your cluster
|
||||
- Look for trends in your environment
|
||||
- Save your logs to a safe location outside of your cluster
|
||||
- Stay informed of events like a container crashing, a pod eviction, or a node dying
|
||||
- More easily debug and troubleshoot problems
|
||||
|
||||
Rancher supports integration with the following services:
|
||||
|
||||
- Elasticsearch
|
||||
- Splunk
|
||||
- Kafka
|
||||
- Syslog
|
||||
- Fluentd
|
||||
|
||||
## How Logging Integrations Work
|
||||
|
||||
Rancher can integrate with popular external services used for event streams, telemetry, or search. These services can log errors and warnings in your Kubernetes infrastructure to a stream.
|
||||
|
||||
These services collect container log events, which are saved to the `/var/log/containers` directory on each of your nodes. The service collects both standard and error events. You can then log into your services to review the events collected, leveraging each service's unique features.
|
||||
|
||||
When configuring Rancher to integrate with these services, you'll have to point Rancher toward the service's endpoint and provide authentication information.
|
||||
|
||||
Additionally, you'll have the opportunity to enter key-value pairs to filter the log events collected. The service will only collect events for containers marked with your configured key-value pairs.
|
||||
|
||||
>**Note:** You can only configure one logging service per cluster or per project.
|
||||
|
||||
## Requirements
|
||||
|
||||
The Docker daemon on each node in the cluster should be [configured](https://docs.docker.com/config/containers/logging/configure/) with the (default) log-driver: `json-file`. You can check the log-driver by running the following command:
|
||||
|
||||
```
|
||||
$ docker info | grep 'Logging Driver'
|
||||
Logging Driver: json-file
|
||||
```
|
||||
|
||||
## Logging Scope
|
||||
|
||||
You can configure logging at either cluster level or project level.
|
||||
|
||||
- Cluster logging writes logs for every pod in the cluster, i.e. in all the projects. For [RKE clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md), it also writes logs for all the Kubernetes system components.
|
||||
- [Project logging](../../../reference-guides/rancher-project-tools/project-logging.md) writes logs for every pod in that particular project.
|
||||
|
||||
Logs that are sent to your logging service are from the following locations:
|
||||
|
||||
- Pod logs stored at `/var/log/containers`.
|
||||
- Kubernetes system components logs stored at `/var/lib/rancher/rke/log/`.
|
||||
|
||||
## Enabling Cluster Logging
|
||||
|
||||
As an [administrator](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to send Kubernetes logs to a logging service.
|
||||
|
||||
1. From the **Global** view, navigate to the cluster that you want to configure cluster logging.
|
||||
|
||||
1. Select **Tools > Logging** in the navigation bar.
|
||||
|
||||
1. Select a logging service and enter the configuration. Refer to the specific service for detailed configuration. Rancher supports integration with the following services:
|
||||
|
||||
- [Elasticsearch](elasticsearch.md)
|
||||
- [Splunk](splunk.md)
|
||||
- [Kafka](kafka.md)
|
||||
- [Syslog](syslog.md)
|
||||
- [Fluentd](fluentd.md)
|
||||
|
||||
1. (Optional) Instead of using the UI to configure the logging services, you can enter custom advanced configurations by clicking on **Edit as File**, which is located above the logging targets. This link is only visible after you select a logging service.
|
||||
|
||||
- With the file editor, enter raw fluentd configuration for any logging service. Refer to the documentation for each logging service on how to setup the output configuration.
|
||||
|
||||
- [Elasticsearch Documentation](https://github.com/uken/fluent-plugin-elasticsearch)
|
||||
- [Splunk Documentation](https://github.com/fluent/fluent-plugin-splunk)
|
||||
- [Kafka Documentation](https://github.com/fluent/fluent-plugin-kafka)
|
||||
- [Syslog Documentation](https://github.com/dlackty/fluent-plugin-remote_syslog)
|
||||
- [Fluentd Documentation](https://docs.fluentd.org/v1.0/articles/out_forward)
|
||||
|
||||
- If the logging service is using TLS, you also need to complete the **SSL Configuration** form.
|
||||
1. Provide the **Client Private Key** and **Client Certificate**. You can either copy and paste them or upload them by using the **Read from a file** button.
|
||||
|
||||
- You can use either a self-signed certificate or one provided by a certificate authority.
|
||||
|
||||
- You can generate a self-signed certificate using an openssl command. For example:
|
||||
|
||||
```
|
||||
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
|
||||
```
|
||||
2. If you are using a self-signed certificate, provide the **CA Certificate PEM**.
|
||||
|
||||
1. (Optional) Complete the **Additional Logging Configuration** form.
|
||||
|
||||
1. **Optional:** Use the **Add Field** button to add custom log fields to your logging configuration. These fields are key value pairs (such as `foo=bar`) that you can use to filter the logs from another system.
|
||||
|
||||
1. Enter a **Flush Interval**. This value determines how often [Fluentd](https://www.fluentd.org/) flushes data to the logging server. Intervals are measured in seconds.
|
||||
|
||||
1. **Include System Log**. The logs from pods in system project and RKE components will be sent to the target. Uncheck it to exclude the system logs.
|
||||
|
||||
1. Click **Test**. Rancher sends a test log to the service.
|
||||
|
||||
> **Note:** This button is replaced with _Dry Run_ if you are using the custom configuration editor. In this case, Rancher calls the fluentd dry run command to validate the configuration.
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** Rancher is now configured to send logs to the selected service. Log into the logging service so that you can start viewing the logs.
|
||||
|
||||
## Related Links
|
||||
|
||||
[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/)
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Elasticsearch
|
||||
---
|
||||
|
||||
If your organization uses [Elasticsearch](https://www.elastic.co/), either on premise or in the cloud, you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Elasticsearch deployment to view logs.
|
||||
|
||||
>**Prerequisites:** Configure an [Elasticsearch deployment](https://www.elastic.co/guide/en/cloud/saas-release/ec-create-deployment.html).
|
||||
|
||||
## Elasticsearch Deployment Configuration
|
||||
|
||||
1. In the **Endpoint** field, enter the IP address and port of your Elasticsearch instance. You can find this information from the dashboard of your Elasticsearch deployment.
|
||||
|
||||
* Elasticsearch usually uses port `9200` for HTTP and `9243` for HTTPS.
|
||||
|
||||
1. If you are using [X-Pack Security](https://www.elastic.co/guide/en/x-pack/current/xpack-introduction.html), enter your Elasticsearch **Username** and **Password** for authentication.
|
||||
|
||||
1. Enter an [Index Pattern](https://www.elastic.co/guide/en/kibana/current/index-patterns.html).
|
||||
|
||||
## SSL Configuration
|
||||
|
||||
If your instance of Elasticsearch uses SSL, your **Endpoint** will need to begin with `https://`. With the correct endpoint, the **SSL Configuration** form is enabled and ready to be completed.
|
||||
|
||||
1. Provide the **Client Private Key** and **Client Certificate**. You can either copy and paste them or upload them by using the **Read from a file** button.
|
||||
|
||||
- You can use either a self-signed certificate or one provided by a certificate authority.
|
||||
|
||||
- You can generate a self-signed certificate using an openssl command. For example:
|
||||
|
||||
```
|
||||
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
|
||||
```
|
||||
|
||||
1. Enter your **Client Key Password**.
|
||||
|
||||
1. Enter your **SSL Version**. The default version is `TLSv1_2`.
|
||||
|
||||
1. Select whether or not you want to verify your SSL.
|
||||
|
||||
* If you are using a self-signed certificate, select **Enabled - Input trusted server certificate**, provide the **CA Certificate PEM**. You can copy and paste the certificate or upload it using the **Read from a file** button.
|
||||
* If you are using a certificate from a certificate authority, select **Enabled - Input trusted server certificate**. You do not need to provide a **CA Certificate PEM**.
|
||||
-33
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Fluentd
|
||||
---
|
||||
|
||||
If your organization uses [Fluentd](https://www.fluentd.org/), you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Fluentd server to view logs.
|
||||
|
||||
>**Prerequisites:** Configure Fluentd input forward to receive the event stream.
|
||||
>
|
||||
>See [Fluentd Documentation](https://docs.fluentd.org/v1.0/articles/in_forward) for details.
|
||||
|
||||
## Fluentd Configuration
|
||||
|
||||
You can add multiple Fluentd Servers. First, click **Add Fluentd Server**. For each Fluentd server, complete the configuration information:
|
||||
|
||||
1. In the **Endpoint** field, enter the address and port of your Fluentd instance, e.g. `http://Fluentd-server:24224`.
|
||||
|
||||
1. Enter the **Shared Key** if your Fluentd Server is using a shared key for authentication.
|
||||
|
||||
1. Enter the **Username** and **Password** if your Fluentd Server is using username and password for authentication.
|
||||
|
||||
1. **Optional:** Enter the **Hostname** of the Fluentd server.
|
||||
|
||||
1. Enter the load balancing **Weight** of the Fluentd server. If the weight of one server is 20 and the other server is 30, events will be sent in a 2:3 ratio. If you do not enter a weight, the default weight is 60.
|
||||
|
||||
1. If this server is a standby server, check **Use as Standby Only**. Standby servers are used when all other servers are not available.
|
||||
|
||||
After adding all the Fluentd servers, you have the option to select **Enable Gzip Compression**. By default, this is enabled because the transferred payload size will be reduced.
|
||||
|
||||
## SSL Configuration
|
||||
|
||||
If your Fluentd servers are using TLS, you need to select **Use TLS**. If you are using a self-signed certificate, provide the **CA Certificate PEM**. You can copy and paste the certificate or upload it using the **Read from a file** button.
|
||||
|
||||
>**Note:** Fluentd does not support self-signed certificates when client authentication is enabled.
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Kafka
|
||||
---
|
||||
|
||||
If your organization uses [Kafka](https://kafka.apache.org/), you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Kafka server to view logs.
|
||||
|
||||
>**Prerequisite:** You must have a Kafka server configured.
|
||||
|
||||
## Kafka Server Configuration
|
||||
|
||||
1. Select the type of **Endpoint** your Kafka server is using:
|
||||
|
||||
* **Zookeeper**: Enter the IP address and port. By default, Zookeeper uses port `2181`. Please note that a Zookeeper endpoint cannot enable TLS.
|
||||
* **Broker**: Click on **Add Endpoint**. For each Kafka broker, enter the IP address and port. By default, Kafka brokers use port `9092`.
|
||||
|
||||
1. In the **Topic** field, enter the name of a Kafka [topic](https://kafka.apache.org/documentation/#basic_ops_add_topic) that your Kubernetes cluster submits logs to.
|
||||
|
||||
## **Broker** Endpoint Type
|
||||
|
||||
### SSL Configuration
|
||||
|
||||
If your Kafka cluster is using SSL for the **Broker**, you need to complete the **SSL Configuration** form.
|
||||
|
||||
1. Provide the **Client Private Key** and **Client Certificate**. You can either copy and paste them or upload them by using the **Read from a file** button.
|
||||
|
||||
1. Provide the **CA Certificate PEM**. You can either copy and paste the certificate or upload it using the **Read from a file** button.
|
||||
|
||||
>**Note:** Kafka does not support self-signed certificates when client authentication is enabled.
|
||||
|
||||
### SASL configuration
|
||||
|
||||
If your Kafka cluster is using [SASL authentication](https://kafka.apache.org/documentation/#security_sasl) for the Broker, you need to complete the **SASL Configuration** form.
|
||||
|
||||
1. Enter the SASL **Username** and **Password**.
|
||||
|
||||
1. Select the **SASL Type** that your Kafka cluster is using.
|
||||
|
||||
* If your Kafka is using **Plain**, please ensure your Kafka cluster is using SSL.
|
||||
|
||||
* If your Kafka is using **Scram**, you need to select which **Scram Mechanism** Kafka is using.
|
||||
-72
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Splunk
|
||||
---
|
||||
|
||||
If your organization uses [Splunk](https://www.splunk.com/), you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Splunk server to view logs.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- Configure HTTP event collection for your Splunk Server (Splunk Enterprise or Splunk Cloud).
|
||||
>- Either create a new token or copy an existing token.
|
||||
>
|
||||
>For more information, see [Splunk Documentation](http://docs.splunk.com/Documentation/Splunk/7.1.2/Data/UsetheHTTPEventCollector#About_Event_Collector_tokens).
|
||||
|
||||
## Splunk Configuration
|
||||
|
||||
1. In the **Endpoint** field, enter the IP address and port for you Splunk instance (i.e. `http://splunk-server:8088`)
|
||||
|
||||
* Splunk usually uses port `8088`. If you're using Splunk Cloud, you'll need to work with [Splunk support](https://www.splunk.com/en_us/support-and-services.html) to get an endpoint URL.
|
||||
|
||||
1. Enter the **Token** you obtained while completing the prerequisites (i.e., when you created a token in Splunk).
|
||||
|
||||
1. In the **Source** field, enter the name of the token as entered in Splunk.
|
||||
|
||||
1. **Optional:** Provide one or more [index](http://docs.splunk.com/Documentation/Splunk/7.1.2/Indexer/Aboutindexesandindexers) that's allowed for your token.
|
||||
|
||||
## SSL Configuration
|
||||
|
||||
If your instance of Splunk uses SSL, your **Endpoint** will need to begin with `https://`. With the correct endpoint, the **SSL Configuration** form is enabled and ready to be completed.
|
||||
|
||||
1. Provide the **Client Private Key** and **Client Certificate**. You can either copy and paste them or upload them by using the **Read from a file** button.
|
||||
|
||||
- You can use either a self-signed certificate or one provided by a certificate authority.
|
||||
|
||||
- You can generate a self-signed certificate using an openssl command. For example:
|
||||
|
||||
```
|
||||
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
|
||||
```
|
||||
|
||||
1. Enter your **Client Key Password**.
|
||||
|
||||
1. Select whether or not you want to verify your SSL.
|
||||
|
||||
* If you are using a self-signed certificate, select **Enabled - Input trusted server certificate**, provide the **CA Certificate PEM**. You can copy and paste the certificate or upload it using the **Read from a file** button.
|
||||
* If you are using a certificate from a certificate authority, select **Enabled - Input trusted server certificate**. You do not need to provide a **CA Certificate PEM**.
|
||||
|
||||
## Viewing Logs
|
||||
|
||||
1. Log into your Splunk server.
|
||||
|
||||
1. Click on **Search & Reporting**. The number of **Indexed Events** listed should be increasing.
|
||||
|
||||
1. Click on Data Summary and select the Sources tab.
|
||||
|
||||
|
||||
1. To view the actual logs, click on the source that you declared earlier.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
You can use curl to see if **HEC** is listening for HTTP event data.
|
||||
|
||||
```
|
||||
$ curl http://splunk-server:8088/services/collector/event \
|
||||
-H 'Authorization: Splunk 8da70994-b1b0-4a79-b154-bfaae8f93432' \
|
||||
-d '{"event": "hello world"}'
|
||||
```
|
||||
|
||||
If Splunk is configured correctly, you should receive **json** data returning `success code 0`. You should be able
|
||||
to send logging data to HEC.
|
||||
|
||||
If you received an error, check your configuration in Splunk and Rancher.
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Syslog
|
||||
---
|
||||
|
||||
If your organization uses [Syslog](https://tools.ietf.org/html/rfc5424), you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Syslog server to view logs.
|
||||
|
||||
>**Prerequisite:** You must have a Syslog server configured.
|
||||
|
||||
If you are using rsyslog, please make sure your rsyslog authentication mode is `x509/name`.
|
||||
|
||||
## Syslog Server Configuration
|
||||
|
||||
1. In the **Endpoint** field, enter the IP address and port for your Syslog server. Additionally, in the dropdown, select the protocol that your Syslog server uses.
|
||||
|
||||
1. In the **Program** field, enter the name of the application sending logs to your Syslog server, e.g. `Rancher`.
|
||||
|
||||
1. If you are using a cloud logging service, e.g. [Sumologic](https://www.sumologic.com/), enter a **Token** that authenticates with your Syslog server. You will need to create this token in the cloud logging service.
|
||||
|
||||
1. Select a **Log Severity** for events that are logged to the Syslog server. For more information on each severity level, see the [Syslog protocol documentation](https://tools.ietf.org/html/rfc5424#page-11).
|
||||
|
||||
- By specifying a **Log Severity** does not mean that will act as a filtering mechanism for logs. To do that you should use a parser on the Syslog server.
|
||||
|
||||
## Encryption Configuration
|
||||
|
||||
If your Syslog server is using **TCP** protocol and uses TLS, you need to select **Use TLS** and complete the **Encryption Configuration** form.
|
||||
|
||||
1. Provide the **Client Private Key** and **Client Certificate**. You can either copy and paste them or upload them by using the **Read from a file** button.
|
||||
|
||||
- You can use either a self-signed certificate or one provided by a certificate authority.
|
||||
|
||||
- You can generate a self-signed certificate using an openssl command. For example:
|
||||
|
||||
```
|
||||
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
|
||||
```
|
||||
|
||||
1. Select whether or not you want to verify your SSL.
|
||||
|
||||
* If you are using a self-signed certificate, select **Enabled - Input trusted server certificate**, provide the **CA Certificate PEM**. You can copy and paste the certificate or upload it using the **Read from a file** button.
|
||||
* If you are using a certificate from a certificate authority, select **Enabled - Input trusted server certificate**. You do not need to provide a **CA Certificate PEM**.
|
||||
-112
@@ -1,112 +0,0 @@
|
||||
---
|
||||
title: Cluster Metrics
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Cluster metrics display the hardware utilization for all nodes in your cluster, regardless of its role. They give you a global monitoring insight into the cluster.
|
||||
|
||||
Some of the biggest metrics to look out for:
|
||||
|
||||
- **CPU Utilization**
|
||||
|
||||
High load either indicates that your cluster is running efficiently or that you're running out of CPU resources.
|
||||
|
||||
- **Disk Utilization**
|
||||
|
||||
Be on the lookout for increased read and write rates on nodes nearing their disk capacity. This advice is especially true for etcd nodes, as running out of storage on an etcd node leads to cluster failure.
|
||||
|
||||
- **Memory Utilization**
|
||||
|
||||
Deltas in memory utilization usually indicate a memory leak.
|
||||
|
||||
- **Load Average**
|
||||
|
||||
Generally, you want your load average to match your number of logical CPUs for the cluster. For example, if your cluster has 8 logical CPUs, the ideal load average would be 8 as well. If you load average is well under the number of logical CPUs for the cluster, you may want to reduce cluster resources. On the other hand, if your average is over 8, your cluster may need more resources.
|
||||
|
||||
## Finding Node Metrics
|
||||
|
||||
1. From the **Global** view, navigate to the cluster that you want to view metrics.
|
||||
|
||||
1. Select **Nodes** in the navigation bar.
|
||||
|
||||
1. Select a specific node and click on its name.
|
||||
|
||||
1. Click on **Node Metrics**.
|
||||
|
||||
[_Get expressions for Cluster Metrics_](./expression.md#cluster-metrics)
|
||||
|
||||
### Etcd Metrics
|
||||
|
||||
>**Note:** Only supported for [Rancher launched Kubernetes clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md).
|
||||
|
||||
Etcd metrics display the operations of the etcd database on each of your cluster nodes. After establishing a baseline of normal etcd operational metrics, observe them for abnormal deltas between metric refreshes, which indicate potential issues with etcd. Always address etcd issues immediately!
|
||||
|
||||
You should also pay attention to the text at the top of the etcd metrics, which displays leader election statistics. This text indicates if etcd currently has a leader, which is the etcd instance that coordinates the other etcd instances in your cluster. A large increase in leader changes implies etcd is unstable. If you notice a change in leader election statistics, you should investigate them for issues.
|
||||
|
||||
Some of the biggest metrics to look out for:
|
||||
|
||||
- **Etcd has a leader**
|
||||
|
||||
etcd is usually deployed on multiple nodes and elects a leader to coordinate its operations. If etcd does not have a leader, its operations are not being coordinated.
|
||||
|
||||
- **Number of leader changes**
|
||||
|
||||
If this statistic suddenly grows, it usually indicates network communication issues that constantly force the cluster to elect a new leader.
|
||||
|
||||
[_Get expressions for Etcd Metrics_](./expression.md#etcd-metrics)
|
||||
|
||||
### Kubernetes Components Metrics
|
||||
|
||||
Kubernetes components metrics display data about the cluster's individual Kubernetes components. Primarily, it displays information about connections and latency for each component: the API server, controller manager, scheduler, and ingress controller.
|
||||
|
||||
>**Note:** The metrics for the controller manager, scheduler and ingress controller are only supported for [Rancher launched Kubernetes clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md).
|
||||
|
||||
When analyzing Kubernetes component metrics, don't be concerned about any single standalone metric in the charts and graphs that display. Rather, you should establish a baseline for metrics considered normal following a period of observation, e.g. the range of values that your components usually operate within and are considered normal. After you establish this baseline, be on the lookout for large deltas in the charts and graphs, as these big changes usually indicate a problem that you need to investigate.
|
||||
|
||||
Some of the more important component metrics to monitor are:
|
||||
|
||||
- **API Server Request Latency**
|
||||
|
||||
Increasing API response times indicate there's a generalized problem that requires investigation.
|
||||
|
||||
- **API Server Request Rate**
|
||||
|
||||
Rising API request rates usually coincide with increased API response times. Increased request rates also indicate a generalized problem requiring investigation.
|
||||
|
||||
- **Scheduler Preemption Attempts**
|
||||
|
||||
If you see a spike in scheduler preemptions, it's an indication that you're running out of hardware resources, as Kubernetes is recognizing it doesn't have enough resources to run all your pods and is prioritizing the more important ones.
|
||||
|
||||
- **Scheduling Failed Pods**
|
||||
|
||||
Failed pods can have a variety of causes, such as unbound persistent volume claims, exhausted hardware resources, non-responsive nodes, etc.
|
||||
|
||||
- **Ingress Controller Request Process Time**
|
||||
|
||||
How fast ingress is routing connections to your cluster services.
|
||||
|
||||
[_Get expressions for Kubernetes Component Metrics_](./expression.md#kubernetes-components-metrics)
|
||||
|
||||
## Rancher Logging Metrics
|
||||
|
||||
Although the Dashboard for a cluster primarily displays data sourced from Prometheus, it also displays information for cluster logging, provided that you have [configured Rancher to use a logging service](../cluster-logging/cluster-logging.md).
|
||||
|
||||
[_Get expressions for Rancher Logging Metrics_](./expression.md#rancher-logging-metrics)
|
||||
|
||||
## Finding Workload Metrics
|
||||
|
||||
Workload metrics display the hardware utilization for a Kubernetes workload. You can also view metrics for [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [stateful sets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) and so on.
|
||||
|
||||
1. From the **Global** view, navigate to the project that you want to view workload metrics.
|
||||
|
||||
1. From the main navigation bar, choose **Resources > Workloads.** In versions before v2.3.0, choose **Workloads** on the main navigation bar.
|
||||
|
||||
1. Select a specific workload and click on its name.
|
||||
|
||||
1. In the **Pods** section, select a specific pod and click on its name.
|
||||
|
||||
- **View the Pod Metrics:** Click on **Pod Metrics**.
|
||||
- **View the Container Metrics:** In the **Containers** section, select a specific container and click on its name. Click on **Container Metrics**.
|
||||
|
||||
[_Get expressions for Workload Metrics_](./expression.md#workload-metrics)
|
||||
-110
@@ -1,110 +0,0 @@
|
||||
---
|
||||
title: Integrating Rancher and Prometheus for Cluster Monitoring
|
||||
description: Prometheus lets you view metrics from your different Rancher and Kubernetes objects. Learn about the scope of monitoring and how to enable cluster monitoring
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/monitoring-and-alerting"/>
|
||||
</head>
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with [Prometheus](https://prometheus.io/), a leading open-source monitoring solution.
|
||||
|
||||
## About Prometheus
|
||||
|
||||
Prometheus provides a _time series_ of your data, which is, according to [Prometheus documentation](https://prometheus.io/docs/concepts/data_model/):
|
||||
|
||||
You can configure these services to collect logs at either the cluster level or the project level. This page describes how to enable monitoring for a cluster. For details on enabling monitoring for a project, refer to the [project administration section](project-monitoring.md).
|
||||
|
||||
>A stream of timestamped values belonging to the same metric and the same set of labeled dimensions, along with comprehensive statistics and metrics of the monitored cluster.
|
||||
|
||||
In other words, Prometheus lets you view metrics from your different Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or [Grafana](https://grafana.com/), which is an analytics viewing platform deployed along with Prometheus.
|
||||
|
||||
By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, restore crashed servers, etc.
|
||||
|
||||
Multi-tenancy support in terms of cluster-only and project-only Prometheus instances are also supported.
|
||||
|
||||
## Monitoring Scope
|
||||
|
||||
Using Prometheus, you can monitor Rancher at both the cluster level and [project level](project-monitoring.md). For each cluster and project that is enabled for monitoring, Rancher deploys a Prometheus server.
|
||||
|
||||
- Cluster monitoring allows you to view the health of your Kubernetes cluster. Prometheus collects metrics from the cluster components below, which you can view in graphs and charts.
|
||||
|
||||
- Kubernetes control plane
|
||||
- etcd database
|
||||
- All nodes (including workers)
|
||||
|
||||
- [Project monitoring](project-monitoring.md) allows you to view the state of pods running in a given project. Prometheus collects metrics from the project's deployed HTTP and TCP/UDP workloads.
|
||||
|
||||
## Enabling Cluster Monitoring
|
||||
|
||||
As an [administrator](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md) or [cluster owner](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.
|
||||
|
||||
> **Prerequisites:** The following TCP ports need to be opened for metrics scraping:
|
||||
>
|
||||
> | Port | Node type | Component |
|
||||
> | --- | --- | --- |
|
||||
> | 9796 | Worker | Node exporter |
|
||||
> | 10254 | Worker | Nginx Ingress Controller |
|
||||
> | 10250 | Worker/Controlplane | Kubelet |
|
||||
> | 10251 | Controlplane | Kube scheduler |
|
||||
> | 10252 | Controlplane | Kube controller manager |
|
||||
> | 2379 | Etcd | Etcd server |
|
||||
|
||||
> Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to [migrate to Monitoring V2.](/versioned_docs/version-2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5%2B-monitoring.md)
|
||||
|
||||
1. From the **Global** view, navigate to the cluster that you want to configure cluster monitoring.
|
||||
|
||||
1. Select **Tools > Monitoring** in the navigation bar.
|
||||
|
||||
1. Select **Enable** to show the [Prometheus configuration options](prometheus.md). Review the [resource consumption recommendations](#resource-consumption) to ensure you have enough resources for Prometheus and on your worker nodes to enable monitoring. Enter in your desired configuration options.
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
**Result:** The Prometheus server will be deployed as well as two monitoring applications. The two monitoring applications, `cluster-monitoring` and `monitoring-operator`, are added as an [application](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) to the cluster's `system` project. After the applications are `active`, you can start viewing [cluster metrics](cluster-metrics.md) through the Rancher dashboard or directly from Grafana.
|
||||
|
||||
> The default username and password for the Grafana instance will be `admin/admin`. However, Grafana dashboards are served via the Rancher authentication proxy, so only users who are currently authenticated into the Rancher server have access to the Grafana dashboard.
|
||||
|
||||
## Resource Consumption
|
||||
|
||||
When enabling cluster monitoring, you need to ensure your worker nodes and Prometheus pod have enough resources. The tables below provides a guide of how much resource consumption will be used. In larger deployments, it is strongly advised that the monitoring infrastructure be placed on dedicated nodes in the cluster.
|
||||
|
||||
### Resource Consumption of Prometheus Pods
|
||||
|
||||
This table is the resource consumption of the Prometheus pod, which is based on the number of all the nodes in the cluster. The count of nodes includes the worker, control plane and etcd nodes. Total disk space allocation should be approximated by the `rate * retention` period set at the cluster level. When enabling cluster level monitoring, you should adjust the CPU and Memory limits and reservation.
|
||||
|
||||
Number of Cluster Nodes | CPU (milli CPU) | Memory | Disk
|
||||
------------------------|-----|--------|------
|
||||
5 | 500 | 650 MB | ~1 GB/Day
|
||||
50| 2000 | 2 GB | ~5 GB/Day
|
||||
256| 4000 | 6 GB | ~18 GB/Day
|
||||
|
||||
Additional pod resource requirements for cluster level monitoring.
|
||||
|
||||
| Workload | Container | CPU - Request | Mem - Request | CPU - Limit | Mem - Limit | Configurable |
|
||||
|---------------------|---------------------------------|---------------|---------------|-------------|-------------|--------------|
|
||||
| Prometheus | prometheus | 750m | 750Mi | 1000m | 1000Mi | Y |
|
||||
| | prometheus-proxy | 50m | 50Mi | 100m | 100Mi | Y |
|
||||
| | prometheus-auth | 100m | 100Mi | 500m | 200Mi | Y |
|
||||
| | prometheus-config-reloader | - | - | 50m | 50Mi | N |
|
||||
| | rules-configmap-reloader | - | - | 100m | 25Mi | N |
|
||||
| Grafana | grafana-init-plugin-json-copy | 50m | 50Mi | 50m | 50Mi | Y |
|
||||
| | grafana-init-plugin-json-modify | 50m | 50Mi | 50m | 50Mi | Y |
|
||||
| | grafana | 100m | 100Mi | 200m | 200Mi | Y |
|
||||
| | grafana-proxy | 50m | 50Mi | 100m | 100Mi | Y |
|
||||
| Kube-State Exporter | kube-state | 100m | 130Mi | 100m | 200Mi | Y |
|
||||
| Node Exporter | exporter-node | 200m | 200Mi | 200m | 200Mi | Y |
|
||||
| Operator | prometheus-operator | 100m | 50Mi | 200m | 100Mi | Y |
|
||||
|
||||
|
||||
### Resource Consumption of Other Pods
|
||||
|
||||
Besides the Prometheus pod, there are components that are deployed that require additional resources on the worker nodes.
|
||||
|
||||
Pod | CPU (milli CPU) | Memory (MB)
|
||||
----|-----------------|------------
|
||||
Node Exporter (Per Node) | 100 | 30
|
||||
Kube State Cluster Monitor | 100 | 130
|
||||
Grafana | 100 | 150
|
||||
Prometheus Cluster Monitoring Nginx | 50 | 50
|
||||
-486
@@ -1,486 +0,0 @@
|
||||
---
|
||||
title: Prometheus Custom Metrics Adapter
|
||||
---
|
||||
|
||||
After you've enabled [cluster level monitoring](cluster-monitoring.md), You can view the metrics data from Rancher. You can also deploy the Prometheus custom metrics adapter then you can use the HPA with metrics stored in cluster monitoring.
|
||||
|
||||
## Deploy Prometheus Custom Metrics Adapter
|
||||
|
||||
We are going to use the [Prometheus custom metrics adapter](https://github.com/DirectXMan12/k8s-prometheus-adapter/releases/tag/v0.5.0), version v0.5.0. This is a great example for the [custom metrics server](https://github.com/kubernetes-incubator/custom-metrics-apiserver). And you must be the *cluster owner* to execute following steps.
|
||||
|
||||
- Get the service account of the cluster monitoring is using. It should be configured in the workload ID: `statefulset:cattle-prometheus:prometheus-cluster-monitoring`. And if you didn't customize anything, the service account name should be `cluster-monitoring`.
|
||||
|
||||
- Grant permission to that service account. You will need two kinds of permission.
|
||||
One role is `extension-apiserver-authentication-reader` in `kube-system`, so you will need to create a `Rolebinding` to in `kube-system`. This permission is to get api aggregation configuration from config map in `kube-system`.
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: RoleBinding
|
||||
metadata:
|
||||
name: custom-metrics-auth-reader
|
||||
namespace: kube-system
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: Role
|
||||
name: extension-apiserver-authentication-reader
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cluster-monitoring
|
||||
namespace: cattle-prometheus
|
||||
```
|
||||
|
||||
The other one is cluster role `system:auth-delegator`, so you will need to create a `ClusterRoleBinding`. This permission is to have subject access review permission.
|
||||
|
||||
```yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: custom-metrics:system:auth-delegator
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: system:auth-delegator
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cluster-monitoring
|
||||
namespace: cattle-prometheus
|
||||
```
|
||||
|
||||
- Create configuration for custom metrics adapter. Following is an example configuration. There will be a configuration details in next session.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: adapter-config
|
||||
namespace: cattle-prometheus
|
||||
data:
|
||||
config.yaml: |
|
||||
rules:
|
||||
- seriesQuery: '{__name__=~"^container_.*",container_name!="POD",namespace!="",pod_name!=""}'
|
||||
seriesFilters: []
|
||||
resources:
|
||||
overrides:
|
||||
namespace:
|
||||
resource: namespace
|
||||
pod_name:
|
||||
resource: pod
|
||||
name:
|
||||
matches: ^container_(.*)_seconds_total$
|
||||
as: ""
|
||||
metricsQuery: sum(rate(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}[1m])) by (<<.GroupBy>>)
|
||||
- seriesQuery: '{__name__=~"^container_.*",container_name!="POD",namespace!="",pod_name!=""}'
|
||||
seriesFilters:
|
||||
- isNot: ^container_.*_seconds_total$
|
||||
resources:
|
||||
overrides:
|
||||
namespace:
|
||||
resource: namespace
|
||||
pod_name:
|
||||
resource: pod
|
||||
name:
|
||||
matches: ^container_(.*)_total$
|
||||
as: ""
|
||||
metricsQuery: sum(rate(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}[1m])) by (<<.GroupBy>>)
|
||||
- seriesQuery: '{__name__=~"^container_.*",container_name!="POD",namespace!="",pod_name!=""}'
|
||||
seriesFilters:
|
||||
- isNot: ^container_.*_total$
|
||||
resources:
|
||||
overrides:
|
||||
namespace:
|
||||
resource: namespace
|
||||
pod_name:
|
||||
resource: pod
|
||||
name:
|
||||
matches: ^container_(.*)$
|
||||
as: ""
|
||||
metricsQuery: sum(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}) by (<<.GroupBy>>)
|
||||
- seriesQuery: '{namespace!="",__name__!~"^container_.*"}'
|
||||
seriesFilters:
|
||||
- isNot: .*_total$
|
||||
resources:
|
||||
template: <<.Resource>>
|
||||
name:
|
||||
matches: ""
|
||||
as: ""
|
||||
metricsQuery: sum(<<.Series>>{<<.LabelMatchers>>}) by (<<.GroupBy>>)
|
||||
- seriesQuery: '{namespace!="",__name__!~"^container_.*"}'
|
||||
seriesFilters:
|
||||
- isNot: .*_seconds_total
|
||||
resources:
|
||||
template: <<.Resource>>
|
||||
name:
|
||||
matches: ^(.*)_total$
|
||||
as: ""
|
||||
metricsQuery: sum(rate(<<.Series>>{<<.LabelMatchers>>}[1m])) by (<<.GroupBy>>)
|
||||
- seriesQuery: '{namespace!="",__name__!~"^container_.*"}'
|
||||
seriesFilters: []
|
||||
resources:
|
||||
template: <<.Resource>>
|
||||
name:
|
||||
matches: ^(.*)_seconds_total$
|
||||
as: ""
|
||||
metricsQuery: sum(rate(<<.Series>>{<<.LabelMatchers>>}[1m])) by (<<.GroupBy>>)
|
||||
resourceRules:
|
||||
cpu:
|
||||
containerQuery: sum(rate(container_cpu_usage_seconds_total{<<.LabelMatchers>>}[1m])) by (<<.GroupBy>>)
|
||||
nodeQuery: sum(rate(container_cpu_usage_seconds_total{<<.LabelMatchers>>, id='/'}[1m])) by (<<.GroupBy>>)
|
||||
resources:
|
||||
overrides:
|
||||
instance:
|
||||
resource: node
|
||||
namespace:
|
||||
resource: namespace
|
||||
pod_name:
|
||||
resource: pod
|
||||
containerLabel: container_name
|
||||
memory:
|
||||
containerQuery: sum(container_memory_working_set_bytes{<<.LabelMatchers>>}) by (<<.GroupBy>>)
|
||||
nodeQuery: sum(container_memory_working_set_bytes{<<.LabelMatchers>>,id='/'}) by (<<.GroupBy>>)
|
||||
resources:
|
||||
overrides:
|
||||
instance:
|
||||
resource: node
|
||||
namespace:
|
||||
resource: namespace
|
||||
pod_name:
|
||||
resource: pod
|
||||
containerLabel: container_name
|
||||
window: 1m
|
||||
```
|
||||
|
||||
- Create HTTPS TLS certs for your api server. You can use following command to create a self-signed cert.
|
||||
|
||||
```bash
|
||||
openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out serving.crt -keyout serving.key -subj "/C=CN/CN=custom-metrics-apiserver.cattle-prometheus.svc.cluster.local"
|
||||
# And you will find serving.crt and serving.key in your path. And then you are going to create a secret in cattle-prometheus namespace.
|
||||
kubectl create secret generic -n cattle-prometheus cm-adapter-serving-certs --from-file=serving.key=./serving.key --from-file=serving.crt=./serving.crt
|
||||
```
|
||||
|
||||
- Then you can create the prometheus custom metrics adapter. And you will need a service for this deployment too. Creating it via Import YAML or Rancher would do. Please create those resources in `cattle-prometheus` namespaces.
|
||||
|
||||
Here is the prometheus custom metrics adapter deployment.
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
labels:
|
||||
app: custom-metrics-apiserver
|
||||
name: custom-metrics-apiserver
|
||||
namespace: cattle-prometheus
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: custom-metrics-apiserver
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: custom-metrics-apiserver
|
||||
name: custom-metrics-apiserver
|
||||
spec:
|
||||
serviceAccountName: cluster-monitoring
|
||||
containers:
|
||||
- name: custom-metrics-apiserver
|
||||
image: directxman12/k8s-prometheus-adapter-amd64:v0.5.0
|
||||
args:
|
||||
- --secure-port=6443
|
||||
- --tls-cert-file=/var/run/serving-cert/serving.crt
|
||||
- --tls-private-key-file=/var/run/serving-cert/serving.key
|
||||
- --logtostderr=true
|
||||
- --prometheus-url=http://prometheus-operated/
|
||||
- --metrics-relist-interval=1m
|
||||
- --v=10
|
||||
- --config=/etc/adapter/config.yaml
|
||||
ports:
|
||||
- containerPort: 6443
|
||||
volumeMounts:
|
||||
- mountPath: /var/run/serving-cert
|
||||
name: volume-serving-cert
|
||||
readOnly: true
|
||||
- mountPath: /etc/adapter/
|
||||
name: config
|
||||
readOnly: true
|
||||
- mountPath: /tmp
|
||||
name: tmp-vol
|
||||
volumes:
|
||||
- name: volume-serving-cert
|
||||
secret:
|
||||
secretName: cm-adapter-serving-certs
|
||||
- name: config
|
||||
configMap:
|
||||
name: adapter-config
|
||||
- name: tmp-vol
|
||||
emptyDir: {}
|
||||
|
||||
```
|
||||
|
||||
Here is the service of the deployment.
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: custom-metrics-apiserver
|
||||
namespace: cattle-prometheus
|
||||
spec:
|
||||
ports:
|
||||
- port: 443
|
||||
targetPort: 6443
|
||||
selector:
|
||||
app: custom-metrics-apiserver
|
||||
```
|
||||
|
||||
- Create API service for your custom metric server.
|
||||
|
||||
```yaml
|
||||
apiVersion: apiregistration.k8s.io/v1beta1
|
||||
kind: APIService
|
||||
metadata:
|
||||
name: v1beta1.custom.metrics.k8s.io
|
||||
spec:
|
||||
service:
|
||||
name: custom-metrics-apiserver
|
||||
namespace: cattle-prometheus
|
||||
group: custom.metrics.k8s.io
|
||||
version: v1beta1
|
||||
insecureSkipTLSVerify: true
|
||||
groupPriorityMinimum: 100
|
||||
versionPriority: 100
|
||||
|
||||
```
|
||||
|
||||
- Then you can verify your custom metrics server by `kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1`. If you see the return datas from the api, it means that the metrics server has been successfully set up.
|
||||
|
||||
- You create HPA with custom metrics now. Here is an example of HPA. You will need to create a nginx deployment in your namespace first.
|
||||
|
||||
```yaml
|
||||
kind: HorizontalPodAutoscaler
|
||||
apiVersion: autoscaling/v2beta1
|
||||
metadata:
|
||||
name: nginx
|
||||
spec:
|
||||
scaleTargetRef:
|
||||
# point the HPA at the nginx deployment you just created
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
name: nginx
|
||||
# autoscale between 1 and 10 replicas
|
||||
minReplicas: 1
|
||||
maxReplicas: 10
|
||||
metrics:
|
||||
# use a "Pods" metric, which takes the average of the
|
||||
# given metric across all pods controlled by the autoscaling target
|
||||
- type: Pods
|
||||
pods:
|
||||
metricName: memory_usage_bytes
|
||||
targetAverageValue: 5000000
|
||||
```
|
||||
|
||||
And then, you should see your nginx is scaling up. HPA with custom metrics works.
|
||||
|
||||
## Configuration of prometheus custom metrics adapter
|
||||
|
||||
> Refer to https://github.com/DirectXMan12/k8s-prometheus-adapter/blob/master/docs/config.md
|
||||
|
||||
The adapter determines which metrics to expose, and how to expose them,
|
||||
through a set of "discovery" rules. Each rule is executed independently
|
||||
(so make sure that your rules are mutually exclusive), and specifies each
|
||||
of the steps the adapter needs to take to expose a metric in the API.
|
||||
|
||||
Each rule can be broken down into roughly four parts:
|
||||
|
||||
- *Discovery*, which specifies how the adapter should find all Prometheus
|
||||
metrics for this rule.
|
||||
|
||||
- *Association*, which specifies how the adapter should determine which
|
||||
Kubernetes resources a particular metric is associated with.
|
||||
|
||||
- *Naming*, which specifies how the adapter should expose the metric in
|
||||
the custom metrics API.
|
||||
|
||||
- *Querying*, which specifies how a request for a particular metric on one
|
||||
or more Kubernetes objects should be turned into a query to Prometheus.
|
||||
|
||||
A basic config with one rule might look like:
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
# this rule matches cumulative cAdvisor metrics measured in seconds
|
||||
- seriesQuery: '{__name__=~"^container_.*",container_name!="POD",namespace!="",pod_name!=""}'
|
||||
resources:
|
||||
# skip specifying generic resource<->label mappings, and just
|
||||
# attach only pod and namespace resources by mapping label names to group-resources
|
||||
overrides:
|
||||
namespace: {resource: "namespace"},
|
||||
pod_name: {resource: "pod"},
|
||||
# specify that the `container_` and `_seconds_total` suffixes should be removed.
|
||||
# this also introduces an implicit filter on metric family names
|
||||
name:
|
||||
# we use the value of the capture group implicitly as the API name
|
||||
# we could also explicitly write `as: "$1"`
|
||||
matches: "^container_(.*)_seconds_total$"
|
||||
# specify how to construct a query to fetch samples for a given series
|
||||
# This is a Go template where the `.Series` and `.LabelMatchers` string values
|
||||
# are available, and the delimiters are `<<` and `>>` to avoid conflicts with
|
||||
# the prometheus query language
|
||||
metricsQuery: "sum(rate(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}[2m])) by (<<.GroupBy>>)"
|
||||
```
|
||||
|
||||
### Discovery
|
||||
|
||||
Discovery governs the process of finding the metrics that you want to
|
||||
expose in the custom metrics API. There are two fields that factor into
|
||||
discovery: `seriesQuery` and `seriesFilters`.
|
||||
|
||||
`seriesQuery` specifies Prometheus series query (as passed to the
|
||||
`/api/v1/series` endpoint in Prometheus) to use to find some set of
|
||||
Prometheus series. The adapter will strip the label values from this
|
||||
series, and then use the resulting metric-name-label-names combinations
|
||||
later on.
|
||||
|
||||
In many cases, `seriesQuery` will be sufficient to narrow down the list of
|
||||
Prometheus series. However, sometimes (especially if two rules might
|
||||
otherwise overlap), it's useful to do additional filtering on metric
|
||||
names. In this case, `seriesFilters` can be used. After the list of
|
||||
series is returned from `seriesQuery`, each series has its metric name
|
||||
filtered through any specified filters.
|
||||
|
||||
Filters may be either:
|
||||
|
||||
- `is: <regex>`, which matches any series whose name matches the specified
|
||||
regex.
|
||||
|
||||
- `isNot: <regex>`, which matches any series whose name does not match the
|
||||
specified regex.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
# match all cAdvisor metrics that aren't measured in seconds
|
||||
seriesQuery: '{__name__=~"^container_.*_total",container_name!="POD",namespace!="",pod_name!=""}'
|
||||
seriesFilters:
|
||||
isNot: "^container_.*_seconds_total"
|
||||
```
|
||||
|
||||
### Association
|
||||
|
||||
Association governs the process of figuring out which Kubernetes resources
|
||||
a particular metric could be attached to. The `resources` field controls
|
||||
this process.
|
||||
|
||||
There are two ways to associate resources with a particular metric. In
|
||||
both cases, the value of the label becomes the name of the particular
|
||||
object.
|
||||
|
||||
One way is to specify that any label name that matches some particular
|
||||
pattern refers to some group-resource based on the label name. This can
|
||||
be done using the `template` field. The pattern is specified as a Go
|
||||
template, with the `Group` and `Resource` fields representing group and
|
||||
resource. You don't necessarily have to use the `Group` field (in which
|
||||
case the group is guessed by the system). For instance:
|
||||
|
||||
```yaml
|
||||
# any label `kube_<group>_<resource>` becomes <group>.<resource> in Kubernetes
|
||||
resources:
|
||||
template: "kube_<<.Group>>_<<.Resource>>"
|
||||
```
|
||||
|
||||
The other way is to specify that some particular label represents some
|
||||
particular Kubernetes resource. This can be done using the `overrides`
|
||||
field. Each override maps a Prometheus label to a Kubernetes
|
||||
group-resource. For instance:
|
||||
|
||||
```yaml
|
||||
# the microservice label corresponds to the apps.deployment resource
|
||||
resource:
|
||||
overrides:
|
||||
microservice: {group: "apps", resource: "deployment"}
|
||||
```
|
||||
|
||||
These two can be combined, so you can specify both a template and some
|
||||
individual overrides.
|
||||
|
||||
The resources mentioned can be any resource available in your kubernetes
|
||||
cluster, as long as you've got a corresponding label.
|
||||
|
||||
### Naming
|
||||
|
||||
Naming governs the process of converting a Prometheus metric name into
|
||||
a metric in the custom metrics API, and vice versa. It's controlled by
|
||||
the `name` field.
|
||||
|
||||
Naming is controlled by specifying a pattern to extract an API name from
|
||||
a Prometheus name, and potentially a transformation on that extracted
|
||||
value.
|
||||
|
||||
The pattern is specified in the `matches` field, and is just a regular
|
||||
expression. If not specified, it defaults to `.*`.
|
||||
|
||||
The transformation is specified by the `as` field. You can use any
|
||||
capture groups defined in the `matches` field. If the `matches` field
|
||||
doesn't contain capture groups, the `as` field defaults to `$0`. If it
|
||||
contains a single capture group, the `as` field defautls to `$1`.
|
||||
Otherwise, it's an error not to specify the as field.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
# match turn any name <name>_total to <name>_per_second
|
||||
# e.g. http_requests_total becomes http_requests_per_second
|
||||
name:
|
||||
matches: "^(.*)_total$"
|
||||
as: "${1}_per_second"
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
Querying governs the process of actually fetching values for a particular
|
||||
metric. It's controlled by the `metricsQuery` field.
|
||||
|
||||
The `metricsQuery` field is a Go template that gets turned into
|
||||
a Prometheus query, using input from a particular call to the custom
|
||||
metrics API. A given call to the custom metrics API is distilled down to
|
||||
a metric name, a group-resource, and one or more objects of that
|
||||
group-resource. These get turned into the following fields in the
|
||||
template:
|
||||
|
||||
- `Series`: the metric name
|
||||
- `LabelMatchers`: a comma-separated list of label matchers matching the
|
||||
given objects. Currently, this is the label for the particular
|
||||
group-resource, plus the label for namespace, if the group-resource is
|
||||
namespaced.
|
||||
- `GroupBy`: a comma-separated list of labels to group by. Currently,
|
||||
this contains the group-resource label used in `LabelMatchers`.
|
||||
|
||||
For instance, suppose we had a series `http_requests_total` (exposed as
|
||||
`http_requests_per_second` in the API) with labels `service`, `pod`,
|
||||
`ingress`, `namespace`, and `verb`. The first four correspond to
|
||||
Kubernetes resources. Then, if someone requested the metric
|
||||
`pods/http_request_per_second` for the pods `pod1` and `pod2` in the
|
||||
`somens` namespace, we'd have:
|
||||
|
||||
- `Series: "http_requests_total"`
|
||||
- `LabelMatchers: "pod=~\"pod1|pod2",namespace="somens"`
|
||||
- `GroupBy`: `pod`
|
||||
|
||||
Additionally, there are two advanced fields that are "raw" forms of other
|
||||
fields:
|
||||
|
||||
- `LabelValuesByName`: a map mapping the labels and values from the
|
||||
`LabelMatchers` field. The values are pre-joined by `|`
|
||||
(for used with the `=~` matcher in Prometheus).
|
||||
- `GroupBySlice`: the slice form of `GroupBy`.
|
||||
|
||||
In general, you'll probably want to use the `Series`, `LabelMatchers`, and
|
||||
`GroupBy` fields. The other two are for advanced usage.
|
||||
|
||||
The query is expected to return one value for each object requested. The
|
||||
adapter will use the labels on the returned series to associate a given
|
||||
series back to its corresponding object.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
# convert cumulative cAdvisor metrics into rates calculated over 2 minutes
|
||||
metricsQuery: "sum(rate(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}[2m])) by (<<.GroupBy>>)"
|
||||
```
|
||||
-365
@@ -1,365 +0,0 @@
|
||||
---
|
||||
title: Prometheus Expressions
|
||||
---
|
||||
|
||||
The PromQL expressions in this doc can be used to configure [alerts.](../cluster-alerts/cluster-alerts.md)
|
||||
|
||||
> Before expressions can be used in alerts, monitoring must be enabled. For more information, refer to the documentation on enabling monitoring [at the cluster level](cluster-monitoring.md) or [at the project level.](./project-monitoring.md)
|
||||
|
||||
For more information about querying Prometheus, refer to the official [Prometheus documentation.](https://prometheus.io/docs/prometheus/latest/querying/basics/)
|
||||
|
||||
## Cluster Metrics
|
||||
|
||||
### Cluster CPU Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))` |
|
||||
| Summary | `1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))` |
|
||||
|
||||
### Cluster Load Average
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>load1</td><td>`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`</td></tr><tr><td>load5</td><td>`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`</td></tr><tr><td>load15</td><td>`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>load1</td><td>`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})`</td></tr><tr><td>load5</td><td>`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})`</td></tr><tr><td>load15</td><td>`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})`</td></tr></table> |
|
||||
|
||||
### Cluster Memory Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)` |
|
||||
| Summary | `1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)` |
|
||||
|
||||
### Cluster Disk Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)` |
|
||||
| Summary | `(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})` |
|
||||
|
||||
### Cluster Disk I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>read</td><td>`sum(rate(node_disk_read_bytes_total[5m])) by (instance)`</td></tr><tr><td>written</td><td>`sum(rate(node_disk_written_bytes_total[5m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>read</td><td>`sum(rate(node_disk_read_bytes_total[5m]))`</td></tr><tr><td>written</td><td>`sum(rate(node_disk_written_bytes_total[5m]))`</td></tr></table> |
|
||||
|
||||
### Cluster Network Packets
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr></table> |
|
||||
| Summary | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr></table> |
|
||||
|
||||
### Cluster Network I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive</td><td><code>sum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr><tr><td>transmit</td><td><code>sum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)</code></td></tr></table> |
|
||||
| Summary | <table><tr><td>receive</td><td><code>sum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr><tr><td>transmit</td><td><code>sum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))</code></td></tr></table> |
|
||||
|
||||
## Node Metrics
|
||||
|
||||
### Node CPU Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `avg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)` |
|
||||
| Summary | `1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))` |
|
||||
|
||||
### Node Load Average
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>load1</td><td>`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr><tr><td>load5</td><td>`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr><tr><td>load15</td><td>`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr></table> |
|
||||
| Summary | <table><tr><td>load1</td><td>`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr><tr><td>load5</td><td>`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr><tr><td>load15</td><td>`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`</td></tr></table> |
|
||||
|
||||
### Node Memory Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})` |
|
||||
| Summary | `1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"}) ` |
|
||||
|
||||
### Node Disk Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)` |
|
||||
| Summary | `(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})` |
|
||||
|
||||
### Node Disk I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>read</td><td>`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`</td></tr><tr><td>written</td><td>`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`</td></tr></table> |
|
||||
| Summary | <table><tr><td>read</td><td>`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`</td></tr><tr><td>written</td><td>`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`</td></tr></table> |
|
||||
|
||||
### Node Network Packets
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr></table> |
|
||||
| Summary | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr></table> |
|
||||
|
||||
### Node Network I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive</td><td><code>sum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit</td><td><code>sum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)</code></td></tr></table> |
|
||||
| Summary | <table><tr><td>receive</td><td><code>sum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit</td><td><code>sum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))</code></td></tr></table> |
|
||||
|
||||
## Etcd Metrics
|
||||
|
||||
### Etcd Has a Leader
|
||||
|
||||
`max(etcd_server_has_leader)`
|
||||
|
||||
### Number of Times the Leader Changes
|
||||
|
||||
`max(etcd_server_leader_changes_seen_total)`
|
||||
|
||||
### Number of Failed Proposals
|
||||
|
||||
`sum(etcd_server_proposals_failed_total)`
|
||||
|
||||
### GRPC Client Traffic
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>in</td><td>`sum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)`</td></tr><tr><td>out</td><td>`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>in</td><td>`sum(rate(etcd_network_client_grpc_received_bytes_total[5m]))`</td></tr><tr><td>out</td><td>`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))`</td></tr></table> |
|
||||
|
||||
### Peer Traffic
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>in</td><td>`sum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)`</td></tr><tr><td>out</td><td>`sum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>in</td><td>`sum(rate(etcd_network_peer_received_bytes_total[5m]))`</td></tr><tr><td>out</td><td>`sum(rate(etcd_network_peer_sent_bytes_total[5m]))`</td></tr></table> |
|
||||
|
||||
### DB Size
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)` |
|
||||
| Summary | `sum(etcd_debugging_mvcc_db_total_size_in_bytes)` |
|
||||
|
||||
### Active Streams
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>lease-watch</td><td>`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)`</td></tr><tr><td>watch</td><td>`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>lease-watch</td><td>`sum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})`</td></tr><tr><td>watch</td><td>`sum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})`</td></tr></table> |
|
||||
|
||||
### Raft Proposals
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>applied</td><td>`sum(increase(etcd_server_proposals_applied_total[5m])) by (instance)`</td></tr><tr><td>committed</td><td>`sum(increase(etcd_server_proposals_committed_total[5m])) by (instance)`</td></tr><tr><td>pending</td><td>`sum(increase(etcd_server_proposals_pending[5m])) by (instance)`</td></tr><tr><td>failed</td><td>`sum(increase(etcd_server_proposals_failed_total[5m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>applied</td><td>`sum(increase(etcd_server_proposals_applied_total[5m]))`</td></tr><tr><td>committed</td><td>`sum(increase(etcd_server_proposals_committed_total[5m]))`</td></tr><tr><td>pending</td><td>`sum(increase(etcd_server_proposals_pending[5m]))`</td></tr><tr><td>failed</td><td>`sum(increase(etcd_server_proposals_failed_total[5m]))`</td></tr></table> |
|
||||
|
||||
### RPC Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>total</td><td>`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)`</td></tr><tr><td>fail</td><td>`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>total</td><td>`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))`</td></tr><tr><td>fail</td><td>`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))`</td></tr></table> |
|
||||
|
||||
### Disk Operations
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>commit-called-by-backend</td><td>`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)`</td></tr><tr><td>fsync-called-by-wal</td><td>`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>commit-called-by-backend</td><td>`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))`</td></tr><tr><td>fsync-called-by-wal</td><td>`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))`</td></tr></table> |
|
||||
|
||||
### Disk Sync Duration
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>wal</td><td>`histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))`</td></tr><tr><td>db</td><td>`histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))`</td></tr></table> |
|
||||
| Summary | <table><tr><td>wal</td><td>`sum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))`</td></tr><tr><td>db</td><td>`sum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))`</td></tr></table> |
|
||||
|
||||
## Kubernetes Components Metrics
|
||||
|
||||
### API Server Request Latency
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06` |
|
||||
| Summary | `avg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06` |
|
||||
|
||||
### API Server Request Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(apiserver_request_count[5m])) by (instance, code)` |
|
||||
| Summary | `sum(rate(apiserver_request_count[5m])) by (instance)` |
|
||||
|
||||
### Scheduling Failed Pods
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(kube_pod_status_scheduled{condition="false"})` |
|
||||
| Summary | `sum(kube_pod_status_scheduled{condition="false"})` |
|
||||
|
||||
### Controller Manager Queue Depth
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>volumes</td><td>`sum(volumes_depth) by instance`</td></tr><tr><td>deployment</td><td>`sum(deployment_depth) by instance`</td></tr><tr><td>replicaset</td><td>`sum(replicaset_depth) by instance`</td></tr><tr><td>service</td><td>`sum(service_depth) by instance`</td></tr><tr><td>serviceaccount</td><td>`sum(serviceaccount_depth) by instance`</td></tr><tr><td>endpoint</td><td>`sum(endpoint_depth) by instance`</td></tr><tr><td>daemonset</td><td>`sum(daemonset_depth) by instance`</td></tr><tr><td>statefulset</td><td>`sum(statefulset_depth) by instance`</td></tr><tr><td>replicationmanager</td><td>`sum(replicationmanager_depth) by instance`</td></tr></table> |
|
||||
| Summary | <table><tr><td>volumes</td><td>`sum(volumes_depth)`</td></tr><tr><td>deployment</td><td>`sum(deployment_depth)`</td></tr><tr><td>replicaset</td><td>`sum(replicaset_depth)`</td></tr><tr><td>service</td><td>`sum(service_depth)`</td></tr><tr><td>serviceaccount</td><td>`sum(serviceaccount_depth)`</td></tr><tr><td>endpoint</td><td>`sum(endpoint_depth)`</td></tr><tr><td>daemonset</td><td>`sum(daemonset_depth)`</td></tr><tr><td>statefulset</td><td>`sum(statefulset_depth)`</td></tr><tr><td>replicationmanager</td><td>`sum(replicationmanager_depth)`</td></tr></table> |
|
||||
|
||||
### Scheduler E2E Scheduling Latency
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06` |
|
||||
| Summary | `sum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)` |
|
||||
|
||||
### Scheduler Preemption Attempts
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(scheduler_total_preemption_attempts[5m])) by (instance)` |
|
||||
| Summary | `sum(rate(scheduler_total_preemption_attempts[5m]))` |
|
||||
|
||||
### Ingress Controller Connections
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>reading</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)`</td></tr><tr><td>waiting</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)`</td></tr><tr><td>writing</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)`</td></tr><tr><td>accepted</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)`</td></tr><tr><td>active</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)`</td></tr><tr><td>handled</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>reading</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="reading"})`</td></tr><tr><td>waiting</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"})`</td></tr><tr><td>writing</td><td>`sum(nginx_ingress_controller_nginx_process_connections{state="writing"})`</td></tr><tr><td>accepted</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))`</td></tr><tr><td>active</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))`</td></tr><tr><td>handled</td><td>`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))`</td></tr></table> |
|
||||
|
||||
### Ingress Controller Request Process Time
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `topk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` |
|
||||
| Summary | `topk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))` |
|
||||
|
||||
## Rancher Logging Metrics
|
||||
|
||||
### Fluentd Buffer Queue Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)` |
|
||||
| Summary | `sum(rate(fluentd_output_status_buffer_queue_length[5m]))` |
|
||||
|
||||
### Fluentd Input Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(fluentd_input_status_num_records_total[5m])) by (instance)` |
|
||||
| Summary | `sum(rate(fluentd_input_status_num_records_total[5m]))` |
|
||||
|
||||
### Fluentd Output Errors Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(fluentd_output_status_num_errors[5m])) by (type)` |
|
||||
| Summary | `sum(rate(fluentd_output_status_num_errors[5m]))` |
|
||||
|
||||
### Fluentd Output Rate
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(rate(fluentd_output_status_num_records_total[5m])) by (instance)` |
|
||||
| Summary | `sum(rate(fluentd_output_status_num_records_total[5m]))` |
|
||||
|
||||
## Workload Metrics
|
||||
|
||||
### Workload CPU Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>cfs throttled seconds</td><td>`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>user seconds</td><td>`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>system seconds</td><td>`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>usage seconds</td><td>`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>cfs throttled seconds</td><td>`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>user seconds</td><td>`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>system seconds</td><td>`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>usage seconds</td><td>`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Workload Memory Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)` |
|
||||
| Summary | `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})` |
|
||||
|
||||
### Workload Network Packets
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive-packets</td><td>`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>receive-dropped</td><td>`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>receive-errors</td><td>`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>transmit-packets</td><td>`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>transmit-dropped</td><td>`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>transmit-errors</td><td>`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>receive-packets</td><td>`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-dropped</td><td>`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-errors</td><td>`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-packets</td><td>`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-dropped</td><td>`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-errors</td><td>`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Workload Network I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive</td><td>`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>transmit</td><td>`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>receive</td><td>`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit</td><td>`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Workload Disk I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>read</td><td>`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr><tr><td>write</td><td>`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>read</td><td>`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr><tr><td>write</td><td>`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
## Pod Metrics
|
||||
|
||||
### Pod CPU Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>cfs throttled seconds</td><td>`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`</td></tr><tr><td>usage seconds</td><td>`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`</td></tr><tr><td>system seconds</td><td>`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`</td></tr><tr><td>user seconds</td><td>`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>cfs throttled seconds</td><td>`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`</td></tr><tr><td>usage seconds</td><td>`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`</td></tr><tr><td>system seconds</td><td>`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`</td></tr><tr><td>user seconds</td><td>`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Pod Memory Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)` |
|
||||
| Summary | `sum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})` |
|
||||
|
||||
### Pod Network Packets
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive-packets</td><td>`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-dropped</td><td>`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-errors</td><td>`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-packets</td><td>`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-dropped</td><td>`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-errors</td><td>`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
| Summary | <table><tr><td>receive-packets</td><td>`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-dropped</td><td>`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>receive-errors</td><td>`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-packets</td><td>`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-dropped</td><td>`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit-errors</td><td>`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Pod Network I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>receive</td><td>`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit</td><td>`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
| Summary | <table><tr><td>receive</td><td>`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>transmit</td><td>`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
### Pod Disk I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| Detail | <table><tr><td>read</td><td>`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`</td></tr><tr><td>write</td><td>`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`</td></tr></table> |
|
||||
| Summary | <table><tr><td>read</td><td>`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr><tr><td>write</td><td>`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`</td></tr></table> |
|
||||
|
||||
## Container Metrics
|
||||
|
||||
### Container CPU Utilization
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| cfs throttled seconds | `sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
| usage seconds | `sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
| system seconds | `sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
| user seconds | `sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
|
||||
### Container Memory Utilization
|
||||
|
||||
`sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})`
|
||||
|
||||
### Container Disk I/O
|
||||
|
||||
| Catalog | Expression |
|
||||
| --- | --- |
|
||||
| read | `sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
| write | `sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))` |
|
||||
-72
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Project Monitoring
|
||||
---
|
||||
|
||||
_Available as of v2.2.4_
|
||||
|
||||
Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with [Prometheus](https://prometheus.io/), a leading open-source monitoring solution.
|
||||
|
||||
|
||||
### Monitoring Scope
|
||||
|
||||
Using Prometheus, you can monitor Rancher at both the [cluster level](cluster-monitoring.md) and project level. For each cluster and project that is enabled for monitoring, Rancher deploys a Prometheus server.
|
||||
|
||||
- [Cluster monitoring](cluster-monitoring.md/) allows you to view the health of your Kubernetes cluster. Prometheus collects metrics from the cluster components below, which you can view in graphs and charts.
|
||||
|
||||
- Kubernetes control plane
|
||||
- etcd database
|
||||
- All nodes (including workers)
|
||||
|
||||
- Project monitoring allows you to view the state of pods running in a given project. Prometheus collects metrics from the project's deployed HTTP and TCP/UDP workloads.
|
||||
|
||||
### Permissions to Configure Project Monitoring
|
||||
|
||||
Only [administrators](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.md), [cluster owners or members](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles), or [project owners](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) can configure project level monitoring. Project members can only view monitoring metrics.
|
||||
|
||||
### Enabling Project Monitoring
|
||||
|
||||
> **Prerequisite:** Cluster monitoring must be [enabled.](cluster-monitoring.md)
|
||||
|
||||
1. Go to the project where monitoring should be enabled. Note: When cluster monitoring is enabled, monitoring is also enabled by default in the **System** project.
|
||||
|
||||
1. Select **Tools > Monitoring** in the navigation bar.
|
||||
|
||||
1. Select **Enable** to show the [Prometheus configuration options](./prometheus.md). Enter in your desired configuration options.
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
### Project-Level Monitoring Resource Requirements
|
||||
|
||||
Container| CPU - Request | Mem - Request | CPU - Limit | Mem - Limit | Configurable
|
||||
---------|---------------|---------------|-------------|-------------|-------------
|
||||
Prometheus|750m| 750Mi | 1000m | 1000Mi | Yes
|
||||
Grafana | 100m | 100Mi | 200m | 200Mi | No
|
||||
|
||||
|
||||
**Result:** A single application,`project-monitoring`, is added as an [application](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) to the project. After the application is `active`, you can start viewing project metrics through the [Rancher dashboard](cluster-monitoring.md/) or directly from Grafana.
|
||||
|
||||
> The default username and password for the Grafana instance will be `admin/admin`. However, Grafana dashboards are served via the Rancher authentication proxy, so only users who are currently authenticated into the Rancher server have access to the Grafana dashboard.
|
||||
|
||||
### Project Metrics
|
||||
[Workload metrics](./expression.md#workload-metrics) are available for the project if monitoring is enabled at the [cluster level](cluster-monitoring.md/) and at the [project level.](#enabling-project-monitoring)
|
||||
|
||||
You can monitor custom metrics from any [exporters.](https://prometheus.io/docs/instrumenting/exporters/) You can also expose some custom endpoints on deployments without needing to configure Prometheus for your project.
|
||||
|
||||
> **Example:**
|
||||
> A [Redis](https://redis.io/) application is deployed in the namespace `redis-app` in the project `Datacenter`. It is monitored via [Redis exporter](https://github.com/oliver006/redis_exporter). After enabling project monitoring, you can edit the application to configure the <b>Advanced Options -> Custom Metrics</b> section. Enter the `Container Port` and `Path` and select the `Protocol`.
|
||||
|
||||
To access a project-level Grafana instance,
|
||||
|
||||
1. From the **Global** view, navigate to a cluster that has monitoring enabled.
|
||||
|
||||
1. Go to a project that has monitoring enabled.
|
||||
|
||||
1. From the project view, click **Apps.** In versions before v2.2.0, choose **Catalog Apps** on the main navigation bar.
|
||||
|
||||
1. Go to the `project-monitoring` application.
|
||||
|
||||
1. In the `project-monitoring` application, there are two `/index.html` links: one that leads to a Grafana instance and one that leads to a Prometheus instance. When you click the Grafana link, it will redirect you to a new webpage for Grafana, which shows metrics for the cluster.
|
||||
|
||||
1. You will be signed in to the Grafana instance automatically. The default username is `admin` and the default password is `admin`. For security, we recommend that you log out of Grafana, log back in with the `admin` password, and change your password.
|
||||
|
||||
**Results:** You will be logged into Grafana from the Grafana instance. After logging in, you can view the preset Grafana dashboards, which are imported via the [Grafana provisioning mechanism](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards), so you cannot modify them directly. For now, if you want to configure your own dashboards, clone the original and modify the new copy.
|
||||
-105
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Prometheus Configuration
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
While configuring monitoring at either the [cluster level](cluster-monitoring.md) or [project level](./project-monitoring.md), there are multiple options that can be configured.
|
||||
|
||||
- [Basic Configuration](#basic-configuration)
|
||||
- [Advanced Options](#advanced-options)
|
||||
- [Node Exporter](#node-exporter)
|
||||
- [Persistent Storage](#persistent-storage)
|
||||
- [Remote Storage](#remote-storage)
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
Option | Description
|
||||
-------|-------------
|
||||
Data Retention | How long your Prometheus instance retains monitoring data scraped from Rancher objects before it's purged.
|
||||
[Enable Node Exporter](#node-exporter) | Whether or not to deploy the node exporter.
|
||||
Node Exporter Host Port | The host port on which data is exposed, i.e. data that Prometheus collects from your node hardware. Required if you have enabled the node exporter.
|
||||
[Enable Persistent Storage](#persistent-storage) for Prometheus | Whether or not to configure storage for Prometheus so that metrics can be retained even if the Prometheus pod fails.
|
||||
[Enable Persistent Storage](#persistent-storage) for Grafana | Whether or not to configure storage for Grafana so that the Grafana dashboards and configuration can be retained even if the Grafana pod fails.
|
||||
Prometheus [CPU Limit](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) | CPU resource limit for the Prometheus pod.
|
||||
Prometheus [CPU Reservation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) | CPU reservation for the Prometheus pod.
|
||||
Prometheus [Memory Limit](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) | Memory resource limit for the Prometheus pod.
|
||||
Prometheus [Memory Reservation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) | Memory resource requests for the Prometheus pod.
|
||||
Selector | Ability to select the nodes in which Prometheus and Grafana pods are deployed to. To use this option, the nodes must have labels.
|
||||
|
||||
## Advanced Options
|
||||
|
||||
Since monitoring is an [application](https://github.com/rancher/system-charts/tree/dev/charts/rancher-monitoring) from the [Rancher catalog](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md), it can be configured like any other catalog application, by passing in values to Helm.
|
||||
|
||||
> **Warning:** Any modification to the application without understanding the entire application can lead to catastrophic errors.
|
||||
|
||||
### Prometheus RemoteRead and RemoteWrite
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
Prometheus RemoteRead and RemoteWrite can be configured as custom answers in the **Advanced Options** section.
|
||||
|
||||
For more information on remote endpoints and storage, refer to the [Prometheus documentation.](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage)
|
||||
|
||||
The Prometheus operator documentation contains the full [RemoteReadSpec](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#remotereadspec) and [RemoteWriteSpec.](https://github.com/prometheus-operator/prometheus-operator/blob/master/Documentation/api.md#remotewritespec)
|
||||
|
||||
An example configuration would be:
|
||||
|
||||
| Variable | Value |
|
||||
|--------------|------------|
|
||||
| `prometheus.remoteWrite[0].url` | `http://mytarget.com` |
|
||||
|
||||
### LivenessProbe and ReadinessProbe
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
Prometheus LivenessProbe and ReadinessProbe can be configured as custom answers in the **Advanced Options** section.
|
||||
|
||||
The Kubernetes probe spec is [here.](https://v1-17.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#probe-v1-core)
|
||||
|
||||
Some example key-value pairs are:
|
||||
|
||||
| Variable | Value |
|
||||
|--------------|------------|
|
||||
| `prometheus.livenessProbe.timeoutSeconds` | 60 |
|
||||
| `prometheus.readinessProbe.timeoutSeconds` | 60 |
|
||||
|
||||
## Node Exporter
|
||||
|
||||
The [node exporter](https://github.com/prometheus/node_exporter/blob/master/README.md) is a popular open source exporter, which exposes the metrics for hardware and \*NIX kernels OS. It is designed to monitor the host system. However, there are still issues with namespaces when running it in a container, mostly around filesystem mount spaces. In order to monitor actual network metrics for the container network, the node exporter must be deployed with the `hostNetwork` mode.
|
||||
|
||||
When configuring Prometheus and enabling the node exporter, enter a host port in the **Node Exporter Host Port** that will not produce port conflicts with existing applications. The host port chosen must be open to allow internal traffic between Prometheus and the Node Exporter.
|
||||
|
||||
>**Warning:** In order for Prometheus to collect the metrics of the node exporter, after enabling cluster monitoring, you must open the <b>Node Exporter Host Port</b> in the host firewall rules to allow intranet access. By default, `9796` is used as that host port.
|
||||
|
||||
## Persistent Storage
|
||||
|
||||
>**Prerequisite:** Configure one or more StorageClasses to use as [persistent storage](../../../how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/create-kubernetes-persistent-storage.md) for your Prometheus or Grafana pod.
|
||||
|
||||
By default, when you enable Prometheus for either a cluster or project, all monitoring data that Prometheus collects is stored on its own pod. With local storage, if the Prometheus or Grafana pods fail, all the data is lost. Rancher recommends configuring an external persistent storage to the cluster. With the external persistent storage, if the Prometheus or Grafana pods fail, the new pods can recover using data from the persistent storage.
|
||||
|
||||
When enabling persistent storage for Prometheus or Grafana, specify the size of the persistent volume and select the StorageClass.
|
||||
|
||||
## Remote Storage
|
||||
|
||||
>**Prerequisite:** Need a remote storage endpoint to be available. The possible list of integrations is available [here](https://prometheus.io/docs/operating/integrations/)
|
||||
|
||||
Using advanced options, remote storage integration for the Prometheus installation can be configured as follows:
|
||||
|
||||
```
|
||||
prometheus.remoteWrite[0].url = http://remote1/push
|
||||
prometheus.remoteWrite[0].remoteTimeout = 33s
|
||||
|
||||
prometheus.remoteWrite[1].url = http://remote2/push
|
||||
|
||||
|
||||
prometheus.remoteRead[0].url = http://remote1/read
|
||||
prometheus.remoteRead[0].proxyUrl = http://proxy.url
|
||||
prometheus.remoteRead[0].bearerToken = token-value
|
||||
|
||||
prometheus.remoteRead[1].url = http://remote2/read
|
||||
prometheus.remoteRead[1].remoteTimeout = 33s
|
||||
prometheus.remoteRead[1].readRecent = true
|
||||
```
|
||||
|
||||
Additional fields can be set up based on the [ReadSpec](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#remotereadspec) and [RemoteWriteSpec](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#remotewritespec)
|
||||
-59
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Viewing Metrics
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
After you've enabled monitoring at either the [cluster level](cluster-monitoring.md) or [project level](./project-monitoring.md), you will want to be start viewing the data being collected. There are multiple ways to view this data.
|
||||
|
||||
## Rancher Dashboard
|
||||
|
||||
>**Note:** This is only available if you've enabled monitoring at the [cluster level](cluster-monitoring.md). Project specific analytics must be viewed using the project's Grafana instance.
|
||||
|
||||
Rancher's dashboards are available at multiple locations:
|
||||
|
||||
- **Cluster Dashboard**: From the **Global** view, navigate to the cluster.
|
||||
- **Node Metrics**: From the **Global** view, navigate to the cluster. Select **Nodes**. Find the individual node and click on its name. Click **Node Metrics.**
|
||||
- **Workload Metrics**: From the **Global** view, navigate to the project. From the main navigation bar, choose **Resources > Workloads.** (In versions before v2.3.0, choose **Workloads** on the main navigation bar.) Find the individual workload and click on its name. Click **Workload Metrics.**
|
||||
- **Pod Metrics**: From the **Global** view, navigate to the project. Select **Workloads > Workloads**. Find the individual workload and click on its name. Find the individual pod and click on its name. Click **Pod Metrics.**
|
||||
- **Container Metrics**: From the **Global** view, navigate to the project. From the main navigation bar, choose **Resources > Workloads.** (In versions before v2.3.0, choose **Workloads** on the main navigation bar.) Find the individual workload and click on its name. Find the individual pod and click on its name. Find the individual container and click on its name. Click **Container Metrics.**
|
||||
|
||||
Prometheus metrics are displayed and are denoted with the Grafana icon. If you click on the icon, the metrics will open a new tab in Grafana.
|
||||
|
||||
Within each Prometheus metrics widget, there are several ways to customize your view.
|
||||
|
||||
- Toggle between two views:
|
||||
- **Detail**: Displays graphs and charts that let you view each event in a Prometheus time series
|
||||
- **Summary** Displays events in a Prometheus time series that are outside the norm.
|
||||
- Change the range of the time series that you're viewing to see a more refined or expansive data sample.
|
||||
- Customize the data sample to display data between specific dates and times.
|
||||
|
||||
When analyzing these metrics, don't be concerned about any single standalone metric in the charts and graphs. Rather, you should establish a baseline for your metrics over the course of time, e.g. the range of values that your components usually operate within and are considered normal. After you establish the baseline, be on the lookout for any large deltas in the charts and graphs, as these big changes usually indicate a problem that you need to investigate.
|
||||
|
||||
## Grafana
|
||||
|
||||
If you've enabled monitoring at either the [cluster level](cluster-monitoring.md) or [project level](./project-monitoring.md), Rancher automatically creates a link to Grafana instance. Use this link to view monitoring data.
|
||||
|
||||
Grafana allows you to query, visualize, alert, and ultimately, understand your cluster and workload data. For more information on Grafana and its capabilities, visit the [Grafana website](https://grafana.com/grafana).
|
||||
|
||||
### Authentication
|
||||
|
||||
Rancher determines which users can access the new Grafana instance, as well as the objects they can view within it, by validating them against the user's [cluster or project roles](../../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md). In other words, a user's access in Grafana mirrors their access in Rancher.
|
||||
|
||||
When you go to the Grafana instance, you will be logged in with the username `admin` and the password `admin`. If you log out and log in again, you will be prompted to change your password. You will only have access to the URL of the Grafana instance if you have access to view the corresponding metrics in Rancher. So for example, if your Rancher permissions are scoped to the project level, you won't be able to see the Grafana instance for cluster-level metrics.
|
||||
|
||||
### Accessing the Cluster-level Grafana Instance
|
||||
|
||||
1. From the **Global** view, navigate to a cluster that has monitoring enabled.
|
||||
|
||||
1. Go to the **System** project view. This project is where the cluster-level Grafana instance runs.
|
||||
|
||||
1. Click **Apps.** In versions before v2.2.0, choose **Catalog Apps** on the main navigation bar.
|
||||
|
||||
1. Go to the `cluster-monitoring` application.
|
||||
|
||||
1. In the `cluster-monitoring` application, there are two `/index.html` links: one that leads to a Grafana instance and one that leads to a Prometheus instance. When you click the Grafana link, it will redirect you to a new webpage for Grafana, which shows metrics for the cluster.
|
||||
|
||||
1. You will be signed in to the Grafana instance automatically. The default username is `admin` and the default password is `admin`. For security, we recommend that you log out of Grafana, log back in with the `admin` password, and change your password.
|
||||
|
||||
**Results:** You are logged into Grafana from the Grafana instance. After logging in, you can view the preset Grafana dashboards, which are imported via the [Grafana provisioning mechanism](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards), so you cannot modify them directly. For now, if you want to configure your own dashboards, clone the original and modify the new copy.
|
||||
-11
@@ -1,11 +0,0 @@
|
||||
---
|
||||
title: Integrations in Rancher
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/cloud-marketplace"/>
|
||||
</head>
|
||||
|
||||
Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI.
|
||||
|
||||
Examples of some of these integrations are [Istio](istio/istio.md) and [CIS Scans](cis-scans/cis-scans.md).
|
||||
-153
@@ -1,153 +0,0 @@
|
||||
---
|
||||
title: CPU and Memory Allocations
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/istio/cpu-and-memory-allocations"/>
|
||||
</head>
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
This section describes the minimum recommended computing resources for the Istio components in a cluster.
|
||||
|
||||
The CPU and memory allocations for each component are [configurable.](#configuring-resource-allocations)
|
||||
|
||||
Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.
|
||||
|
||||
> **Tip:** In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.
|
||||
|
||||
The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each central Istio component.
|
||||
|
||||
In Kubernetes, the resource request indicates that the workload will not deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/)
|
||||
|
||||
Workload | Container | CPU - Request | Mem - Request | CPU - Limit | Mem - Limit | Configurable
|
||||
---------|-----------|---------------|---------------|-------------|-------------|-------------
|
||||
istio-pilot |discovery| 500m | 2048Mi | 1000m | 4096Mi | Y
|
||||
istio-telemetry |mixer| 1000m | 1024Mi | 4800m | 4096Mi | Y
|
||||
istio-policy | mixer | 1000m | 1024Mi | 4800m | 4096Mi | Y
|
||||
istio-tracing | jaeger | 100m | 100Mi | 500m | 1024Mi | Y
|
||||
prometheus | prometheus | 750m | 750Mi | 1000m | 1024Mi | Y
|
||||
grafana | grafana | 100m | 100Mi | 200m | 512Mi | Y
|
||||
Others | - | 500m | 500Mi | - | - | N
|
||||
**Total** | **-** | **3950m** | **5546Mi** | **>12300m** | **>14848Mi** | **-**
|
||||
|
||||
|
||||
## Configuring Resource Allocations
|
||||
|
||||
You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component.
|
||||
|
||||
To make it easier to schedule the workloads to a node, a cluster administrator can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend.
|
||||
|
||||
You can find more information about Istio configuration in the [official Istio documentation](https://istio.io/docs/concepts/what-is-istio).
|
||||
|
||||
To configure the resources allocated to an Istio component,
|
||||
|
||||
1. In Rancher, go to the cluster where you have Istio installed.
|
||||
1. Click **Tools > Istio.** This opens the Istio configuration page.
|
||||
1. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations.
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The resource allocations for the Istio components are updated.
|
||||
|
||||
## Pilot
|
||||
|
||||
[Pilot](https://istio.io/docs/ops/deployment/architecture/#pilot) provides the following:
|
||||
|
||||
- Authentication configuration
|
||||
- Service discovery for the Envoy sidecars
|
||||
- Traffic management capabilities for intelligent routing (A/B tests and canary rollouts)
|
||||
- Configuration for resiliency (timeouts, retries, circuit breakers, etc)
|
||||
|
||||
For more information on Pilot, refer to the [documentation](https://istio.io/docs/concepts/traffic-management/#pilot-and-envoy).
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Pilot CPU Limit | CPU resource limit for the istio-pilot pod.| Yes | 1000
|
||||
Pilot CPU Reservation | CPU reservation for the istio-pilot pod. | Yes | 500
|
||||
Pilot Memory Limit | Memory resource limit for the istio-pilot pod. | Yes | 4096
|
||||
Pilot Memory Reservation | Memory resource requests for the istio-pilot pod. | Yes | 2048
|
||||
Trace sampling Percentage | [Trace sampling percentage](https://istio.io/docs/tasks/telemetry/distributed-tracing/overview/#trace-sampling) | Yes | 1
|
||||
Pilot Selector | Ability to select the nodes in which istio-pilot pod is deployed to. To use this option, the nodes must have labels. | No | n/a
|
||||
|
||||
## Mixer
|
||||
|
||||
[Mixer](https://istio.io/docs/ops/deployment/architecture/#mixer) enforces access control and usage policies across the service mesh. It also integrates with plugins for monitoring tools such as Prometheus. The Envoy sidecar proxy passes telemetry data and monitoring data to Mixer, and Mixer passes the monitoring data to Prometheus.
|
||||
|
||||
For more information on Mixer, policies and telemetry, refer to the [documentation](https://istio.io/docs/concepts/policies-and-telemetry/).
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Mixer Telemetry CPU Limit | CPU resource limit for the istio-telemetry pod.| Yes | 4800
|
||||
Mixer Telemetry CPU Reservation | CPU reservation for the istio-telemetry pod.| Yes | 1000
|
||||
Mixer Telemetry Memory Limit | Memory resource limit for the istio-telemetry pod.| Yes | 4096
|
||||
Mixer Telemetry Memory Reservation | Memory resource requests for the istio-telemetry pod.| Yes | 1024
|
||||
Enable Mixer Policy | Whether or not to deploy the istio-policy. | Yes | False
|
||||
Mixer Policy CPU Limit | CPU resource limit for the istio-policy pod. | Yes, when policy enabled | 4800
|
||||
Mixer Policy CPU Reservation | CPU reservation for the istio-policy pod. | Yes, when policy enabled | 1000
|
||||
Mixer Policy Memory Limit | Memory resource limit for the istio-policy pod. | Yes, when policy enabled | 4096
|
||||
Mixer Policy Memory Reservation | Memory resource requests for the istio-policy pod. | Yes, when policy enabled | 1024
|
||||
Mixer Selector | Ability to select the nodes in which istio-policy and istio-telemetry pods are deployed to. To use this option, the nodes must have labels. | No | n/a
|
||||
|
||||
## Tracing
|
||||
|
||||
[Distributed tracing](https://istio.io/docs/tasks/telemetry/distributed-tracing/overview/) enables users to track a request through a service mesh. This makes it easier to troubleshoot problems with latency, parallelism and serialization.
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Enable Tracing | Whether or not to deploy the istio-tracing. | Yes | True
|
||||
Tracing CPU Limit | CPU resource limit for the istio-tracing pod. | Yes | 500
|
||||
Tracing CPU Reservation | CPU reservation for the istio-tracing pod. | Yes | 100
|
||||
Tracing Memory Limit | Memory resource limit for the istio-tracing pod. | Yes | 1024
|
||||
Tracing Memory Reservation | Memory resource requests for the istio-tracing pod. | Yes | 100
|
||||
Tracing Selector | Ability to select the nodes in which tracing pod is deployed to. To use this option, the nodes must have labels. | No | n/a
|
||||
|
||||
## Ingress Gateway
|
||||
|
||||
The Istio gateway allows Istio features such as monitoring and route rules to be applied to traffic entering the cluster. This gateway is a prerequisite for outside traffic to make requests to Istio.
|
||||
|
||||
For more information, refer to the [documentation](https://istio.io/docs/tasks/traffic-management/ingress/).
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Enable Ingress Gateway | Whether or not to deploy the istio-ingressgateway. | Yes | False
|
||||
Service Type of Istio Ingress Gateway | How to expose the gateway. You can choose NodePort or Loadbalancer | Yes | NodePort
|
||||
Http2 Port | The NodePort for http2 requests | Yes | 31380
|
||||
Https Port | The NodePort for https requests | Yes | 31390
|
||||
Load Balancer IP | Ingress Gateway Load Balancer IP | No | n/a
|
||||
Load Balancer Source Ranges | Ingress Gateway Load Balancer Source Ranges | No | n/a
|
||||
Ingress Gateway CPU Limit | CPU resource limit for the istio-ingressgateway pod. | Yes | 2000
|
||||
Ingress Gateway CPU Reservation | CPU reservation for the istio-ingressgateway pod. | Yes | 100
|
||||
Ingress Gateway Memory Limit | Memory resource limit for the istio-ingressgateway pod. | Yes | 1024
|
||||
Ingress Gateway Memory Reservation | Memory resource requests for the istio-ingressgateway pod. | Yes | 128
|
||||
Ingress Gateway Selector | Ability to select the nodes in which istio-ingressgateway pod is deployed to. To use this option, the nodes must have labels. | No | n/a
|
||||
|
||||
## Prometheus
|
||||
|
||||
You can query for Istio metrics using Prometheus. Prometheus is an open-source systems monitoring and alerting toolkit.
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Prometheus CPU Limit | CPU resource limit for the Prometheus pod.| Yes | 1000
|
||||
Prometheus CPU Reservation | CPU reservation for the Prometheus pod.| Yes | 750
|
||||
Prometheus Memory Limit | Memory resource limit for the Prometheus pod.| Yes | 1024
|
||||
Prometheus Memory Reservation | Memory resource requests for the Prometheus pod.| Yes | 750
|
||||
Retention for Prometheus | How long your Prometheus instance retains data | Yes | 6
|
||||
Prometheus Selector | Ability to select the nodes in which Prometheus pod is deployed to. To use this option, the nodes must have labels.| No | n/a
|
||||
|
||||
## Grafana
|
||||
|
||||
You can visualize metrics with Grafana. Grafana lets you visualize Istio traffic data scraped by Prometheus.
|
||||
|
||||
Option | Description| Required | Default
|
||||
-------|------------|-------|-------
|
||||
Enable Grafana | Whether or not to deploy the Grafana.| Yes | True
|
||||
Grafana CPU Limit | CPU resource limit for the Grafana pod.| Yes, when Grafana enabled | 200
|
||||
Grafana CPU Reservation | CPU reservation for the Grafana pod.| Yes, when Grafana enabled | 100
|
||||
Grafana Memory Limit | Memory resource limit for the Grafana pod.| Yes, when Grafana enabled | 512
|
||||
Grafana Memory Reservation | Memory resource requests for the Grafana pod.| Yes, when Grafana enabled | 100
|
||||
Grafana Selector | Ability to select the nodes in which Grafana pod is deployed to. To use this option, the nodes must have labels. | No | n/a
|
||||
Enable Persistent Storage for Grafana | Enable Persistent Storage for Grafana | Yes, when Grafana enabled | False
|
||||
Source | Use a Storage Class to provision a new persistent volume or Use an existing persistent volume claim | Yes, when Grafana enabled and enabled PV | Use SC
|
||||
Storage Class | Storage Class for provisioning PV for Grafana | Yes, when Grafana enabled, enabled PV and use storage class | Use the default class
|
||||
Persistent Volume Size | The size for the PV you would like to provision for Grafana | Yes, when Grafana enabled, enabled PV and use storage class | 5Gi
|
||||
Existing Claim | Use existing PVC for Grafana | Yes, when Grafana enabled, enabled PV and use existing PVC | n/a
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Disabling Istio
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/istio/disable-istio"/>
|
||||
</head>
|
||||
|
||||
This section describes how to disable Istio in a cluster, namespace, or workload.
|
||||
|
||||
## Disable Istio in a Cluster
|
||||
|
||||
To disable Istio,
|
||||
|
||||
1. From the **Global** view, navigate to the cluster that you want to disable Istio for.
|
||||
1. Click **Tools > Istio.**
|
||||
1. Click **Disable,** then click the red button again to confirm the disable action.
|
||||
|
||||
**Result:** The `cluster-istio` application in the cluster's `system` project gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster.
|
||||
|
||||
## Disable Istio in a Namespace
|
||||
|
||||
1. In the Rancher UI, go to the project that has the namespace where you want to disable Istio.
|
||||
1. On the **Workloads** tab, you will see a list of namespaces and the workloads deployed in them. Go to the namespace where you want to disable and click the **⋮ > Disable Istio Auto Injection.**
|
||||
|
||||
**Result:** When workloads are deployed in this namespace, they will not have the Istio sidecar.
|
||||
|
||||
## Remove the Istio Sidecar from a Workload
|
||||
|
||||
Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar.
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
title: Istio
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/istio"/>
|
||||
</head>
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
[Istio](https://istio.io/) is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.
|
||||
|
||||
As a network of microservices changes and grows, the interactions between them can become more difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.
|
||||
|
||||
Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.
|
||||
|
||||
This service mesh provides features that include but are not limited to the following:
|
||||
|
||||
- Traffic management features
|
||||
- Enhanced monitoring and tracing
|
||||
- Service discovery and routing
|
||||
- Secure connections and service-to-service authentication with mutual TLS
|
||||
- Load balancing
|
||||
- Automatic retries, backoff, and circuit breaking
|
||||
|
||||
After Istio is enabled in a cluster, you can leverage Istio's control plane functionality with `kubectl`.
|
||||
|
||||
Rancher's Istio integration comes with comprehensive visualization aids:
|
||||
|
||||
- **Trace the root cause of errors with Jaeger.** [Jaeger](https://www.jaegertracing.io/) is an open-source tool that provides a UI for a distributed tracing system, which is useful for root cause analysis and for determining what causes poor performance. Distributed tracing allows you to view an entire chain of calls, which might originate with a user request and traverse dozens of microservices.
|
||||
- **Get the full picture of your microservice architecture with Kiali.** [Kiali](https://www.kiali.io/) provides a diagram that shows the services within a service mesh and how they are connected, including the traffic rates and latencies between them. You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.
|
||||
- **Gain insights from time series analytics with Grafana dashboards.** [Grafana](https://grafana.com/) is an analytics platform that allows you to query, visualize, alert on and understand the data gathered by Prometheus.
|
||||
- **Write custom queries for time series data with the Prometheus UI.** [Prometheus](https://prometheus.io/) is a systems monitoring and alerting toolkit. Prometheus scrapes data from your cluster, which is then used by Grafana. A Prometheus UI is also integrated into Rancher, and lets you write custom queries for time series data and see the results in the UI.
|
||||
|
||||
|
||||
Istio needs to be set up by a Rancher administrator or cluster administrator before it can be used in a project.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough [CPU and memory](cpu-and-memory-allocations.md) to run all of the components of Istio.
|
||||
|
||||
## Setup Guide
|
||||
|
||||
Refer to the [setup guide](../../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) for instructions on how to set up Istio and use it in a project.
|
||||
|
||||
## Disabling Istio
|
||||
|
||||
To remove Istio components from a cluster, namespace, or workload, refer to the section on [disabling Istio.](disable-istio.md)
|
||||
|
||||
## Accessing Visualizations
|
||||
|
||||
> By default, only cluster owners have access to Jaeger and Kiali. For instructions on how to allow project members to access them, see [this section.](rbac-for-istio.md)
|
||||
|
||||
After Istio is set up in a cluster, Grafana, Prometheus, Jaeger, and Kiali are available in the Rancher UI.
|
||||
|
||||
Your access to the visualizations depend on your role. Grafana and Prometheus are only available for cluster owners. The Kiali and Jaeger UIs are available only to cluster owners by default, but cluster owners can allow project members to access them by editing the Istio settings. When you go to your project and click **Resources > Istio,** you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.
|
||||
|
||||
To see the visualizations, go to the cluster where Istio is set up and click **Tools > Istio.** You should see links to each UI at the top of the page.
|
||||
|
||||
You can also get to the visualization tools from the project view.
|
||||
|
||||
## Viewing the Kiali Traffic Graph
|
||||
|
||||
1. From the project view in Rancher, click **Resources > Istio.**
|
||||
1. If you are a cluster owner, you can go to the **Traffic Graph** tab. This tab has the Kiali network visualization integrated into the UI.
|
||||
|
||||
## Viewing Traffic Metrics
|
||||
|
||||
Istio’s monitoring features provide visibility into the performance of all your services.
|
||||
|
||||
1. From the project view in Rancher, click **Resources > Istio.**
|
||||
1. Go to the **Traffic Metrics** tab. After traffic is generated in your cluster, you should be able to see metrics for **Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count** and **Request Duration.** Cluster owners can see all of the metrics, while project members can see a subset of the metrics.
|
||||
|
||||
## Architecture
|
||||
|
||||
Istio installs a service mesh that uses [Envoy](https://www.envoyproxy.io) sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.
|
||||
|
||||
Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.
|
||||
|
||||
Enabling Istio in Rancher enables monitoring in the cluster, and enables Istio in all new namespaces that are created in a cluster. You need to manually enable Istio in preexisting namespaces.
|
||||
|
||||
When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.
|
||||
|
||||
For more information on the Istio sidecar, refer to the [Istio docs](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/).
|
||||
|
||||
### Two Ingresses
|
||||
|
||||
By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. To allow Istio to receive external traffic, you need to enable the Istio ingress gateway for the cluster. The result is that your cluster will have two ingresses.
|
||||
|
||||
|
||||
-61
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Role-based Access Control
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/istio/rbac-for-istio"/>
|
||||
</head>
|
||||
|
||||
This section describes the permissions required to access Istio features and how to configure access to the Kiali and Jaeger visualizations.
|
||||
|
||||
## Cluster-level Access
|
||||
|
||||
By default, only cluster administrators can:
|
||||
|
||||
- Enable Istio for the cluster
|
||||
- Configure resource allocations for Istio
|
||||
- View each UI for Prometheus, Grafana, Kiali, and Jaeger
|
||||
|
||||
## Project-level Access
|
||||
|
||||
After Istio is enabled in a cluster, project owners and members have permission to:
|
||||
|
||||
- Enable and disable Istio sidecar auto-injection for namespaces
|
||||
- Add the Istio sidecar to workloads
|
||||
- View the traffic metrics and traffic graph for the cluster
|
||||
- View the Kiali and Jaeger visualizations if cluster administrators give access to project members
|
||||
- Configure Istio's resources (such as the gateway, destination rules, or virtual services) with `kubectl` (This does not apply to read-only project members)
|
||||
|
||||
## Access to Visualizations
|
||||
|
||||
By default, the Kiali and Jaeger visualizations are restricted to the cluster owner because the information in them could be sensitive.
|
||||
|
||||
**Jaeger** provides a UI for a distributed tracing system, which is useful for root cause analysis and for determining what causes poor performance.
|
||||
|
||||
**Kiali** provides a diagram that shows the services within a service mesh and how they are connected.
|
||||
|
||||
Rancher supports giving groups permission to access Kiali and Jaeger, but not individuals.
|
||||
|
||||
To configure who has permission to access the Kiali and Jaeger UI,
|
||||
|
||||
1. Go to the cluster view and click **Tools > Istio.**
|
||||
1. Then go to the **Member Access** section. If you want to restrict access to certain groups, choose **Allow cluster owner and specified members to access Kiali and Jaeger UI.** Search for the groups that you want to have access to Kiali and Jaeger. If you want all members to have access to the tools, click **Allow all members to access Kiali and Jaeger UI.**
|
||||
1. Click **Save.**
|
||||
|
||||
**Result:** The access levels for Kiali and Jaeger have been updated.
|
||||
|
||||
## Summary of Default Permissions for Istio Users
|
||||
|
||||
| Permission | Cluster Administrators | Project Owners | Project Members | Read-only Project Members |
|
||||
|------------------------------------------|----------------|----------------|-----------------|---------------------------|
|
||||
| Enable and disable Istio for the cluster | ✓ | | | |
|
||||
| Configure Istio resource limits | ✓ | | | |
|
||||
| Control who has access to Kiali and the Jaeger UI | ✓ | | | |
|
||||
| Enable and disable Istio for a namespace | ✓ | ✓ | ✓ | |
|
||||
| Enable and disable Istio on workloads | ✓ | ✓ | ✓ | |
|
||||
| Configure Istio with `kubectl` | ✓ | ✓ | ✓ | |
|
||||
| View Prometheus UI and Grafana UI | ✓ | | | |
|
||||
| View Kiali UI and Jaeger UI ([Configurable](#access-to-visualizations)) | ✓ | | | |
|
||||
| View Istio project dashboard, including traffic metrics* | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
* By default, only the cluster owner will see the traffic graph. Project members will see only a subset of traffic metrics. Project members cannot see the traffic graph because it comes from Kiali, and access to Kiali is restricted to cluster owners by default.
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Release Notes
|
||||
---
|
||||
|
||||
## Istio 1.5.8
|
||||
|
||||
### Important note on 1.5.x versions
|
||||
|
||||
When upgrading from any 1.4 version of Istio to any 1.5 version, the Rancher installer will delete several resources in order to complete the upgrade, at which point they will be immediately re-installed. This includes the `istio-reader-service-account`. If your Istio installation is using this service account be aware that any secrets tied to the service account will be deleted. Most notably this will **break specific [multi-cluster deployments](https://archive.istio.io/v1.4/docs/setup/install/multicluster/)**. Downgrades back to 1.4 are not possible.
|
||||
|
||||
See the official upgrade notes for additional information on the 1.5 release and upgrading from 1.4: https://istio.io/latest/news/releases/1.5.x/announcing-1.5/upgrade-notes/
|
||||
|
||||
> **Note:** Rancher continues to use the Helm installation method, which produces a different architecture from an istioctl installation.
|
||||
|
||||
### Known Issues
|
||||
|
||||
* The Kiali traffic graph is currently not working [#24924](https://github.com/istio/istio/issues/24924)
|
||||
@@ -1,193 +0,0 @@
|
||||
---
|
||||
title: Notifiers
|
||||
---
|
||||
|
||||
Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action.
|
||||
|
||||
Rancher integrates with a variety of popular IT services, including:
|
||||
|
||||
- **Slack**: Send alert notifications to your Slack channels.
|
||||
- **Email**: Choose email recipients for alert notifications.
|
||||
- **PagerDuty**: Route notifications to staff by phone, SMS, or personal email.
|
||||
- **WebHooks**: Update a webpage with alert notifications.
|
||||
- **WeChat**: (Available as of v2.2.0) Send alert notifications to your Enterprise WeChat contacts.
|
||||
- **DingTalk**: (Available as of v2.4.6) Send alert notifications to DingTalk using a webhook.
|
||||
- **Microsoft Teams**: (Available as of v2.4.6) Send alert notifications to Teams using a webhook.
|
||||
|
||||
|
||||
## Roles-based Access Control for Notifiers
|
||||
|
||||
Notifiers are configured at the cluster level. This model ensures that only cluster owners need to configure notifiers, leaving project owners to simply configure alerts in the scope of their projects. You don't need to dispense privileges like SMTP server access or cloud account access.
|
||||
|
||||
## Adding Notifiers
|
||||
|
||||
Set up a notifier so that you can begin configuring and sending alerts.
|
||||
|
||||
1. From the **Global View**, open the cluster that you want to add a notifier.
|
||||
1. From the main menu, select **Tools > Notifiers**. Then click **Add Notifier**.
|
||||
1. Select the service you want to use as your notifier, and then fill out the form. For help filling out the form, refer to the configuration section below.
|
||||
1. Click **Test.** You should receive a notification confirming that the notifier is configured correctly.
|
||||
1. Click **Add** to complete adding the notifier.
|
||||
|
||||
**Result:** Your notifier is added to Rancher.
|
||||
|
||||
## Configuration
|
||||
|
||||
- [Slack](#slack)
|
||||
- [Email](#email)
|
||||
- [PagerDuty](#pagerduty)
|
||||
- [Webhook](#webhook)
|
||||
- [WeChat](#wechat)
|
||||
- [DingTalk](#dingtalk)
|
||||
- [Microsoft Teams](#microsoft-teams)
|
||||
|
||||
### Slack
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| URL | From Slack, create a webhook. For instructions, see the [Slack Documentation](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack). Then enter the Slack webhook URL. |
|
||||
| Default Channel | Enter the name of the channel that you want to send alert notifications in the following format: `#<channelname>`. Both public and private channels are supported. |
|
||||
| Proxy URL | Proxy for the Slack webhook. |
|
||||
| Send Resolved Alerts | _Available as of v2.3.0_ Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test**. If the test is successful, the Slack channel you're configuring for the notifier outputs **Slack setting validated.**
|
||||
|
||||
### Email
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| Default Recipient Address | Enter the email address that you want to receive the notification. |
|
||||
| Send Resolved Alerts | _Available as of v2.3.0_ Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
SMTP Server Configuration:
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Sender | Enter an email address available on your mail server that you want to send the notification. |
|
||||
| Host | Enter the IP address or hostname for your SMTP server. Example: `smtp.email.com` |
|
||||
| Port | In the **Port** field, enter the port used for email. Typically, TLS uses `587` and SSL uses `465`. |
|
||||
| Use TLS | If you're using TLS, make sure **Use TLS** is selected. |
|
||||
| Username | Username to authenticate with the SMTP server. |
|
||||
| Password | Password to authenticate with the SMTP server. |
|
||||
|
||||
**Validation:** Click **Test**. If the test is successful, Rancher prints **settings validated** and you receive a test notification email.
|
||||
|
||||
### PagerDuty
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| Default Integration Key | From PagerDuty, create a Prometheus integration. For instructions, see the [PagerDuty Documentation](https://www.pagerduty.com/docs/guides/prometheus-integration-guide/). Then enter the integration key.
|
||||
| Service Key | The same as the integration key. For instructions on creating a Prometheus integration, see the [PagerDuty Documentation](https://www.pagerduty.com/docs/guides/prometheus-integration-guide/). Then enter the integration key. |
|
||||
| Send Resolved Alerts | _Available as of v2.3.0_ Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test**. If the test is successful, your PagerDuty endpoint outputs **PagerDuty setting validated.**
|
||||
|
||||
### Webhook
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| URL | Using the app of your choice, create a webhook URL. |
|
||||
| Proxy URL | Proxy for the webhook. |
|
||||
| Send Resolved Alerts | _Available as of v2.3.0_ Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test**. If the test is successful, the URL you're configuring as a notifier outputs **Webhook setting validated.**
|
||||
|
||||
### WeChat
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| Corporation ID | Enter the "EnterpriseID" of your corporation. You can get it fro the [Profile page](https://work.weixin.qq.com/wework_admin/frame#profile). |
|
||||
| Application Agent ID | From Enterprise WeChat, create an application in the [Application page](https://work.weixin.qq.com/wework_admin/frame#apps), and then enter the "AgentId" of this application. You will also need to enter the application secret. |
|
||||
| Application Secret | The secret that corresponds to the Application Agent ID. |
|
||||
| Recipient Type | Party, tag, or user. |
|
||||
| Default Recipient | The default recipient ID should correspond to the recipient type. It should be the party ID, tag ID or user account that you want to receive the notification. You could get contact information from [Contacts page](https://work.weixin.qq.com/wework_admin/frame#contacts). |
|
||||
| Proxy URL | If you are using a proxy, enter the proxy URL. |
|
||||
| Send Resolved Alerts | _Available as of v2.3.0_ Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test.** If the test is successful, you should receive an alert message.
|
||||
|
||||
### DingTalk
|
||||
|
||||
_Available as of v2.4.6_
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| Webhook URL | Enter the DingTalk webhook URL. For help setting up the webhook, refer to the [DingTalk documentation.](https://www.alibabacloud.com/help/doc-detail/52872.htm) |
|
||||
| Secret | Optional: Enter a secret for the DingTalk webhook. |
|
||||
| Proxy URL | Optional: Enter a proxy for the DingTalk webhook. |
|
||||
| Send Resolved Alerts | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test.** If the test is successful, the DingTalk notifier output is **DingTalk setting validated.**
|
||||
|
||||
### Microsoft Teams
|
||||
|
||||
_Available as of v2.4.6_
|
||||
|
||||
| Field | Explanation |
|
||||
|----------|----------------------|
|
||||
| Name | Enter a **Name** for the notifier. |
|
||||
| Webhook URL | Enter the Microsoft Teams webhook URL. For help setting up the webhook, refer to the [Teams Documentation.](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) |
|
||||
| Proxy URL | Optional: Enter a proxy for the Teams webhook. |
|
||||
| Send Resolved Alerts | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage) |
|
||||
|
||||
**Validation:** Click **Test.** If the test is successful, the Teams notifier output is **MicrosoftTeams setting validated.**
|
||||
|
||||
## Managing Notifiers
|
||||
|
||||
After you set up notifiers, you can manage them. From the **Global** view, open the cluster that you want to manage your notifiers. Select **Tools > Notifiers**. You can:
|
||||
|
||||
- **Edit** their settings that you configured during their initial setup.
|
||||
- **Clone** them, to quickly setup slightly different notifiers.
|
||||
- **Delete** them when they're no longer necessary.
|
||||
|
||||
## Example Payload for a Webhook Alert Notifier
|
||||
|
||||
```json
|
||||
{
|
||||
"receiver": "c-2a3bc:kube-components-alert",
|
||||
"status": "firing",
|
||||
"alerts": [
|
||||
{
|
||||
"status": "firing",
|
||||
"labels": {
|
||||
"alert_name": "Scheduler is unavailable",
|
||||
"alert_type": "systemService",
|
||||
"cluster_name": "mycluster (ID: c-2a3bc)",
|
||||
"component_name": "scheduler",
|
||||
"group_id": "c-2a3bc:kube-components-alert",
|
||||
"logs": "Get http://127.0.0.1:10251/healthz: dial tcp 127.0.0.1:10251: connect: connection refused",
|
||||
"rule_id": "c-2a3bc:kube-components-alert_scheduler-system-service",
|
||||
"severity": "critical"
|
||||
},
|
||||
"annotations": {},
|
||||
"startsAt": "2020-01-30T19:18:13.321684733Z",
|
||||
"endsAt": "0001-01-01T00:00:00Z",
|
||||
"generatorURL": ""
|
||||
}
|
||||
],
|
||||
"groupLabels": {
|
||||
"component_name": "scheduler",
|
||||
"rule_id": "c-2a3bc:kube-components-alert_scheduler-system-service"
|
||||
},
|
||||
"commonLabels": {
|
||||
"alert_name": "Scheduler is unavailable",
|
||||
"alert_type": "systemService",
|
||||
"cluster_name": "mycluster (ID: c-2a3bc)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## What's Next?
|
||||
|
||||
After creating a notifier, set up alerts to receive notifications of Rancher system events.
|
||||
|
||||
- [Cluster owners](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#cluster-roles) can set up alerts at the [cluster level](cluster-alerts/cluster-alerts.md).
|
||||
- [Project owners](../../how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles) can set up alerts at the [project level](../../reference-guides/rancher-project-tools/project-alerts.md).
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
title: OPA Gatekeeper
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/opa-gatekeeper"/>
|
||||
</head>
|
||||
|
||||
_Available as of v2.4.0_
|
||||
|
||||
To ensure consistency and compliance, every organization needs the ability to define and enforce policies in its environment in an automated way. [OPA (Open Policy Agent)](https://www.openpolicyagent.org/) is a policy engine that facilitates policy-based control for cloud native environments. Rancher provides the ability to enable OPA Gatekeeper in Kubernetes clusters, and also installs a couple of built-in policy definitions, which are also called constraint templates.
|
||||
|
||||
OPA provides a high-level declarative language that lets you specify policy as code and ability to extend simple APIs to offload policy decision-making.
|
||||
|
||||
[OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) is a project that provides integration between OPA and Kubernetes. OPA Gatekeeper provides:
|
||||
|
||||
- An extensible, parameterized policy library.
|
||||
- Native Kubernetes CRDs for instantiating the policy library, also called “constraints."
|
||||
- Native Kubernetes CRDs for extending the policy library, also called "constraint templates."
|
||||
- Audit functionality.
|
||||
|
||||
To read more about OPA, please refer to the [official documentation.](https://www.openpolicyagent.org/docs/latest/)
|
||||
|
||||
## How the OPA Gatekeeper Integration Works
|
||||
|
||||
Kubernetes provides the ability to extend API server functionality via admission controller webhooks, which are invoked whenever a resource is created, updated or deleted. Gatekeeper is installed as a validating webhook and enforces policies defined by Kubernetes custom resource definitions. In addition to the admission control usage, Gatekeeper provides the capability to audit existing resources in Kubernetes clusters and mark current violations of enabled policies.
|
||||
|
||||
OPA Gatekeeper is made available via Rancher's Helm system chart, and it is installed in a namespace named `gatekeeper-system.`
|
||||
|
||||
## Enabling OPA Gatekeeper in a Cluster
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> - Only administrators and cluster owners can enable OPA Gatekeeper.
|
||||
> - The dashboard needs to be enabled using the `dashboard` feature flag. For more information, refer to the [section on enabling experimental features.](../../getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/enable-experimental-features.md)
|
||||
|
||||
1. Navigate to the cluster's **Dashboard** view.
|
||||
1. On the left side menu, expand the cluster menu and click on **OPA Gatekeeper.**
|
||||
1. To install Gatekeeper with the default configuration, click on **Enable Gatekeeper (v0.1.0) with defaults.**
|
||||
1. To change any default configuration, click on **Customize Gatekeeper yaml configuration.**
|
||||
|
||||
## Constraint Templates
|
||||
|
||||
[Constraint templates](https://github.com/open-policy-agent/gatekeeper#constraint-templates) are Kubernetes custom resources that define the schema and Rego logic of the OPA policy to be applied by Gatekeeper. For more information on the Rego policy language, refer to the [official documentation.](https://www.openpolicyagent.org/docs/latest/policy-language/)
|
||||
|
||||
When OPA Gatekeeper is enabled, Rancher installs some templates by default.
|
||||
|
||||
To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on **Templates.**
|
||||
|
||||
Rancher also provides the ability to create your own constraint templates by importing YAML definitions.
|
||||
|
||||
## Creating and Configuring Constraints
|
||||
|
||||
[Constraints](https://github.com/open-policy-agent/gatekeeper#constraints) are Kubernetes custom resources that define the scope of objects to which a specific constraint template applies to. The complete policy is defined by constraint templates and constraints together.
|
||||
|
||||
> **Prerequisites:** OPA Gatekeeper must be enabled in the cluster.
|
||||
|
||||
To list the constraints installed, go to the left side menu under OPA Gatekeeper, and click on **Constraints.**
|
||||
|
||||
New constraints can be created from a constraint template.
|
||||
|
||||
Rancher provides the ability to create a constraint by using a convenient form that lets you input the various constraint fields.
|
||||
|
||||
The **Edit as yaml** option is also available to configure the the constraint's yaml definition.
|
||||
|
||||
### Exempting Rancher's System Namespaces from Constraints
|
||||
|
||||
When a constraint is created, ensure that it does not apply to any Rancher or Kubernetes system namespaces. If the system namespaces are not excluded, then it is possible to see many resources under them marked as violations of the constraint.
|
||||
|
||||
To limit the scope of the constraint only to user namespaces, always specify these namespaces under the **Match** field of the constraint.
|
||||
|
||||
Also, the constraint may interfere with other Rancher functionality and deny system workloads from being deployed. To avoid this, exclude all Rancher-specific namespaces from your constraints.
|
||||
|
||||
## Enforcing Constraints in your Cluster
|
||||
|
||||
When the **Enforcement Action** is **Deny,** the constraint is immediately enabled and will deny any requests that violate the policy defined. By default, the enforcement value is **Deny.**
|
||||
|
||||
When the **Enforcement Action** is **Dryrun,** then any resources that violate the policy are only recorded under the constraint's status field.
|
||||
|
||||
To enforce constraints, create a constraint using the form. In the **Enforcement Action** field, choose **Deny.**
|
||||
|
||||
## Audit and Violations in your Cluster
|
||||
|
||||
OPA Gatekeeper runs a periodic audit to check if any existing resource violates any enforced constraint. The audit-interval (default 300s) can be configured while installing Gatekeeper.
|
||||
|
||||
On the Gatekeeper page, any violations of the defined constraints are listed.
|
||||
|
||||
Also under **Constraints,** the number of violations of the constraint can be found.
|
||||
|
||||
The detail view of each constraint lists information about the resource that violated the constraint.
|
||||
|
||||
## Disabling Gatekeeper
|
||||
|
||||
1. Navigate to the cluster's Dashboard view
|
||||
1. On the left side menu, expand the cluster menu and click on **OPA Gatekeeper.**
|
||||
1. Click the **⋮ > Disable**.
|
||||
|
||||
**Result:** Upon disabling OPA Gatekeeper, all constraint templates and constraints will also be deleted.
|
||||
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: FAQ
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/general-faq"/>
|
||||
</head>
|
||||
|
||||
This FAQ is a work in progress designed to answers the questions our users most frequently ask about Rancher v2.x.
|
||||
|
||||
See [Technical FAQ](faq/technical-items.md), for frequently asked technical questions.
|
||||
|
||||
<br/>
|
||||
|
||||
**Does Rancher v2.x support Docker Swarm and Mesos as environment types?**
|
||||
|
||||
When creating an environment in Rancher v2.x, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm.
|
||||
|
||||
<br/>
|
||||
|
||||
**Is it possible to manage Azure Kubernetes Services with Rancher v2.x?**
|
||||
|
||||
Yes.
|
||||
|
||||
<br/>
|
||||
|
||||
**Does Rancher support Windows?**
|
||||
|
||||
As of Rancher 2.3.0, we support Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on [configuring custom clusters for Windows.](how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/use-windows-clusters.md)
|
||||
|
||||
<br/>
|
||||
|
||||
**Does Rancher support Istio?**
|
||||
|
||||
As of Rancher 2.3.0, we support [Istio.](explanations/integrations-in-rancher/istio/istio.md)
|
||||
|
||||
Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along with any CNCF compliant Kubernetes cluster. You can read more about it [here](https://rio.io/)
|
||||
|
||||
<br/>
|
||||
|
||||
**Will Rancher v2.x support Hashicorp's Vault for storing secrets?**
|
||||
|
||||
Secrets management is on our roadmap but we haven't assigned it to a specific release yet.
|
||||
|
||||
<br/>
|
||||
|
||||
**Does Rancher v2.x support RKT containers as well?**
|
||||
|
||||
At this time, we only support Docker.
|
||||
|
||||
<br/>
|
||||
|
||||
**Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and imported Kubernetes?**
|
||||
|
||||
Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave (Weave is available as of v2.2.0). Always refer to the [Rancher Support Matrix](https://rancher.com/support-maintenance-terms/) for details about what is officially supported.
|
||||
|
||||
<br/>
|
||||
|
||||
**Are you planning on supporting Traefik for existing setups?**
|
||||
|
||||
We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches.
|
||||
|
||||
<br/>
|
||||
|
||||
**Can I import OpenShift Kubernetes clusters into v2.x?**
|
||||
|
||||
Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.
|
||||
|
||||
<br/>
|
||||
|
||||
**Are you going to integrate Longhorn?**
|
||||
|
||||
Yes. Longhorn was on a bit of a hiatus while we were working on v2.0. We plan to re-engage on the project.
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
title: Container Network Interface (CNI) Providers
|
||||
description: Learn about Container Network Interface (CNI), the CNI providers Rancher provides, the features they offer, and how to choose a provider for you
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/container-network-interface-providers"/>
|
||||
</head>
|
||||
|
||||
## What is CNI?
|
||||
|
||||
CNI (Container Network Interface), a [Cloud Native Computing Foundation project](https://cncf.io/), consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted.
|
||||
|
||||
Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking.
|
||||
|
||||
|
||||
|
||||
For more information visit [CNI GitHub project](https://github.com/containernetworking/cni).
|
||||
|
||||
### What Network Models are Used in CNI?
|
||||
|
||||
CNI network providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan ([VXLAN](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan)) or an unencapsulated network model such as Border Gateway Protocol ([BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol)).
|
||||
|
||||
#### What is an Encapsulated Network?
|
||||
|
||||
This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP.
|
||||
|
||||
In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected.
|
||||
|
||||
This network model is used when an extended L2 bridge is preferred. This network model is sensitive to L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation.
|
||||
|
||||
CNI network providers using this network model include Flannel, Canal, and Weave.
|
||||
|
||||
|
||||
|
||||
#### What is an Unencapsulated Network?
|
||||
|
||||
This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol).
|
||||
|
||||
In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods.
|
||||
|
||||
This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensitive to latency.
|
||||
|
||||
CNI network providers using this network model include Calico and Romana.
|
||||
|
||||
|
||||
|
||||
### What CNI Providers are Provided by Rancher?
|
||||
|
||||
Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave (Weave is available as of v2.2.0). You can choose your CNI network provider when you create new Kubernetes clusters from Rancher.
|
||||
|
||||
#### Canal
|
||||
|
||||
|
||||
|
||||
Canal is a CNI network provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options.
|
||||
|
||||
In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation.
|
||||
|
||||
Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (healthcheck). For details, refer to [the port requirements for user clusters.](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md)
|
||||
|
||||
|
||||
|
||||
For more information, see the [Canal GitHub Page.](https://github.com/projectcalico/canal)
|
||||
|
||||
#### Flannel
|
||||
|
||||
|
||||
|
||||
Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being [VXLAN](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#vxlan).
|
||||
|
||||
Encapsulated traffic is unencrypted by default. Therefore, flannel provides an experimental backend for encryption, [IPSec](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#ipsec), which makes use of [strongSwan](https://www.strongswan.org/) to establish encrypted IPSec tunnels between Kubernetes workers.
|
||||
|
||||
Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (healthcheck). See [the port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for more details.
|
||||
|
||||
|
||||
|
||||
For more information, see the [Flannel GitHub Page](https://github.com/coreos/flannel).
|
||||
|
||||
#### Calico
|
||||
|
||||
|
||||
|
||||
Calico enables networking and network policy in Kubernetes clusters across the cloud. Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-prem using BGP.
|
||||
|
||||
Calico also provides a stateless IP-in-IP encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies.
|
||||
|
||||
Kubernetes workers should open TCP port `179` (BGP). See [the port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for more details.
|
||||
|
||||
|
||||
|
||||
For more information, see the following pages:
|
||||
|
||||
- [Project Calico Official Site](https://www.projectcalico.org/)
|
||||
- [Project Calico GitHub Page](https://github.com/projectcalico/calico)
|
||||
|
||||
|
||||
#### Weave
|
||||
|
||||
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Weave enables networking and network policy in Kubernetes clusters across the cloud. Additionally, it support encrypting traffic between the peers.
|
||||
|
||||
Kubernetes workers should open TCP port `6783` (control port), UDP port `6783` and UDP port `6784` (data ports). See the [port requirements for user clusters](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for more details.
|
||||
|
||||
For more information, see the following pages:
|
||||
|
||||
- [Weave Net Official Site](https://github.com/weaveworks/weave/blob/master/site/overview.md)
|
||||
|
||||
### CNI Features by Provider
|
||||
|
||||
The following table summarizes the different features available for each CNI network provider provided by Rancher.
|
||||
|
||||
| Provider | Network Model | Route Distribution | Network Policies | Mesh | External Datastore | Encryption | Ingress/Egress Policies |
|
||||
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
|
||||
| Canal | Encapsulated (VXLAN) | No | Yes | No | K8S API | No | Yes |
|
||||
| Flannel | Encapsulated (VXLAN) | No | No | No | K8S API | No | No |
|
||||
| Calico | Encapsulated (VXLAN,IPIP) OR Unencapsulated | Yes | Yes | Yes | Etcd and K8S API | No | Yes |
|
||||
| Weave | Encapsulated | Yes | Yes | Yes | No | Yes | Yes |
|
||||
|
||||
- Network Model: Encapsulated or unencapsulated. For more information, see [What Network Models are Used in CNI?](#what-network-models-are-used-in-cni)
|
||||
|
||||
- Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI network providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have.
|
||||
|
||||
- Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with certain networking plugins.
|
||||
|
||||
- Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters.
|
||||
|
||||
- External Datastore: CNI network providers with this feature need an external datastore for its data.
|
||||
|
||||
- Encryption: This feature allows cyphered and secure network control and data planes.
|
||||
|
||||
- Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications.
|
||||
|
||||
### CNI Community Popularity
|
||||
|
||||
<CNIPopularityTable />
|
||||
|
||||
### Which CNI Provider Should I Use?
|
||||
|
||||
It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs.
|
||||
|
||||
As of Rancher v2.0.7, Canal is the default CNI network provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking.
|
||||
|
||||
### How can I configure a CNI network provider?
|
||||
|
||||
Please see [Cluster Options](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) on how to configure a network provider for your cluster. For more advanced configuration options, please see how to configure your cluster using a [Config File](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#cluster-config-file) and the options for [Network Plug-ins](https://rancher.com/docs/rke/latest/en/config-options/add-ons/network-plugins/).
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: Installing and Configuring kubectl
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/install-and-configure-kubectl"/>
|
||||
</head>
|
||||
|
||||
`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
|
||||
```
|
||||
@@ -1,8 +0,0 @@
|
||||
---
|
||||
title: Networking
|
||||
---
|
||||
|
||||
Networking FAQ's
|
||||
|
||||
- [CNI Providers](container-network-interface-providers.md)
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Rancher is No Longer Needed
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/rancher-is-no-longer-needed"/>
|
||||
</head>
|
||||
|
||||
This page is intended to answer questions about what happens if you don't want Rancher anymore, if you don't want a cluster to be managed by Rancher anymore, or if the Rancher server is deleted.
|
||||
|
||||
|
||||
## If the Rancher server is deleted, what happens to the workloads in my downstream clusters?
|
||||
|
||||
If Rancher is ever deleted or unrecoverable, all workloads in the downstream Kubernetes clusters managed by Rancher will continue to function as normal.
|
||||
|
||||
## If the Rancher server is deleted, how do I access my downstream clusters?
|
||||
|
||||
The capability to access a downstream cluster without Rancher depends on the type of cluster and the way that the cluster was created. To summarize:
|
||||
|
||||
- **Imported clusters:** The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was imported into Rancher.
|
||||
- **Hosted Kubernetes clusters:** If you created the cluster in a cloud-hosted Kubernetes provider such as EKS, GKE, or AKS, you can continue to manage the cluster using your provider's cloud credentials.
|
||||
- **RKE clusters:** To access an [RKE cluster,](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) the cluster must have the [authorized cluster endpoint](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#4-authorized-cluster-endpoint) enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. (The authorized cluster endpoint is enabled by default for RKE clusters.) With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's [authentication proxy.](../reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.md#1-the-authentication-proxy) For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with [kubectl and the kubeconfig file.](../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#authenticating-directly-with-a-downstream-cluster) These clusters will use a snapshot of the authentication as it was configured when Rancher was removed.
|
||||
|
||||
## What if I don't want Rancher anymore?
|
||||
|
||||
If you [installed Rancher on a Kubernetes cluster,](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) remove Rancher by using the [System Tools](../reference-guides/system-tools.md) with the `remove` subcommand.
|
||||
|
||||
If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in.
|
||||
|
||||
Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on [accessing downstream clusters when Rancher is removed.](#if-the-rancher-server-is-deleted-how-do-i-access-my-downstream-clusters)
|
||||
|
||||
## What if I don't want my imported cluster managed by Rancher?
|
||||
|
||||
If an imported cluster is deleted from the Rancher UI, the cluster is detached from Rancher, leaving it intact and accessible by the same methods that were used to access it before it was imported into Rancher.
|
||||
|
||||
To detach the cluster,
|
||||
|
||||
1. From the **Global** view in Rancher, go to the **Clusters** tab.
|
||||
2. Go to the imported cluster that should be detached from Rancher and click **⋮ > Delete.**
|
||||
3. Click **Delete.**
|
||||
|
||||
**Result:** The imported cluster is detached from Rancher and functions normally outside of Rancher.
|
||||
|
||||
## What if I don't want my RKE cluster or hosted Kubernetes cluster managed by Rancher?
|
||||
|
||||
At this time, there is no functionality to detach these clusters from Rancher. In this context, "detach" is defined as the ability to remove Rancher components from the cluster and manage access to the cluster independently of Rancher.
|
||||
|
||||
The capability to manage these clusters without Rancher is being tracked in this [issue.](https://github.com/rancher/rancher/issues/25234)
|
||||
|
||||
For information about how to access clusters if the Rancher server is deleted, refer to [this section.](#if-the-rancher-server-is-deleted-how-do-i-access-my-downstream-clusters)
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: Security FAQ
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/security"/>
|
||||
</head>
|
||||
|
||||
## Is there a Hardening Guide?
|
||||
|
||||
The Hardening Guide is now located in the main [Security](../reference-guides/rancher-security/rancher-security.md) section.
|
||||
|
||||
## What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?
|
||||
|
||||
We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main [Security](../reference-guides/rancher-security/rancher-security.md) section.
|
||||
@@ -1,196 +0,0 @@
|
||||
---
|
||||
title: Technical FAQ
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/technical-items"/>
|
||||
</head>
|
||||
|
||||
## How can I reset the administrator password?
|
||||
|
||||
Docker install:
|
||||
|
||||
```
|
||||
$ docker exec -ti <container_id> reset-password
|
||||
New password for default administrator (user-xxxxx):
|
||||
<new_password>
|
||||
```
|
||||
|
||||
Kubernetes install (Helm):
|
||||
|
||||
```
|
||||
$ KUBECONFIG=./kube_config_rancher-cluster.yml
|
||||
$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- reset-password
|
||||
New password for default administrator (user-xxxxx):
|
||||
<new_password>
|
||||
```
|
||||
|
||||
### RKE add-on install (only supported up to Rancher v2.0.8)
|
||||
|
||||
:::tip
|
||||
> If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
:::
|
||||
|
||||
Kubernetes install (RKE add-on):
|
||||
|
||||
```
|
||||
$ KUBECONFIG=./kube_config_rancher-cluster.yml
|
||||
$ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name=="cattle-server") | .metadata.name') -- reset-password
|
||||
New password for default administrator (user-xxxxx):
|
||||
<new_password>
|
||||
```
|
||||
|
||||
## I deleted/deactivated the last admin, how can I fix it?
|
||||
|
||||
Docker install:
|
||||
|
||||
```
|
||||
$ docker exec -ti <container_id> ensure-default-admin
|
||||
New default administrator (user-xxxxx)
|
||||
New password for default administrator (user-xxxxx):
|
||||
<new_password>
|
||||
```
|
||||
|
||||
Kubernetes install (Helm):
|
||||
```
|
||||
$ KUBECONFIG=./kube_config_rancher-cluster.yml
|
||||
$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin
|
||||
New password for default administrator (user-xxxxx):
|
||||
<new_password>
|
||||
```
|
||||
|
||||
## How can I enable debug logging?
|
||||
|
||||
See [Troubleshooting: Logging](../troubleshooting/other-troubleshooting-tips/logging.md)
|
||||
|
||||
## My ClusterIP does not respond to ping
|
||||
|
||||
ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using `curl` to access the IP and port to see if it responds.
|
||||
|
||||
## Where can I manage Node Templates?
|
||||
|
||||
Node Templates can be accessed by opening your account menu (top right) and selecting `Node Templates`.
|
||||
|
||||
## Why is my Layer-4 Load Balancer in `Pending` state?
|
||||
|
||||
The Layer-4 Load Balancer is created as `type: LoadBalancer`. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in `Pending` state forever. More information can be found on [Cloud Providers](../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/set-up-cloud-providers.md) or [Create External Load Balancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/)
|
||||
|
||||
## Where is the state of Rancher stored?
|
||||
|
||||
- Docker Install: in the embedded etcd of the `rancher/rancher` container, located at `/var/lib/rancher`.
|
||||
- Kubernetes install: in the etcd of the RKE cluster created to run Rancher.
|
||||
|
||||
## How are the supported Docker versions determined?
|
||||
|
||||
We follow the validated Docker versions for upstream Kubernetes releases. The validated versions can be found under [External Dependencies](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.10.md#external-dependencies) in the Kubernetes release CHANGELOG.md.
|
||||
|
||||
## How can I access nodes created by Rancher?
|
||||
|
||||
SSH keys to access the nodes created by Rancher can be downloaded via the **Nodes** view. Choose the node which you want to access and click on the vertical ⋮ button at the end of the row, and choose **Download Keys** as shown in the picture below.
|
||||
|
||||
|
||||
|
||||
Unzip the downloaded zip file, and use the file `id_rsa` to connect to you host. Be sure to use the correct username (`rancher` or `docker` for RancherOS, `ubuntu` for Ubuntu, `ec2-user` for Amazon Linux)
|
||||
|
||||
```
|
||||
$ ssh -i id_rsa user@ip_of_node
|
||||
```
|
||||
|
||||
## How can I automate task X in Rancher?
|
||||
|
||||
The UI consists of static files, and works based on responses of the API. That means every action/task that you can execute in the UI, can be automated via the API. There are 2 ways to do this:
|
||||
|
||||
* Visit `https://your_rancher_ip/v3` and browse the API options.
|
||||
* Capture the API calls when using the UI (Most commonly used for this is [Chrome Developer Tools](https://developers.google.com/web/tools/chrome-devtools/#network) but you can use anything you like)
|
||||
|
||||
## The IP address of a node changed, how can I recover?
|
||||
|
||||
A node is required to have a static IP configured (or a reserved IP via DHCP). If the IP of a node has changed, you will have to remove it from the cluster and readd it. After it is removed, Rancher will update the cluster to the correct state. If the cluster is no longer in `Provisioning` state, the node is removed from the cluster.
|
||||
|
||||
When the IP address of the node changed, Rancher lost connection to the node, so it will be unable to clean the node properly. See [Cleaning cluster nodes](../how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.md) to clean the node.
|
||||
|
||||
When the node is removed from the cluster, and the node is cleaned, you can readd the node to the cluster.
|
||||
|
||||
## How can I add more arguments/binds/environment variables to Kubernetes components in a Rancher Launched Kubernetes cluster?
|
||||
|
||||
You can add more arguments/binds/environment variables via the [Config File](../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md#cluster-config-file) option in Cluster Options. For more information, see the [Extra Args, Extra Binds, and Extra Environment Variables](https://rancher.com/docs/rke/latest/en/config-options/services/services-extras/) in the RKE documentation or browse the [Example Cluster.ymls](https://rancher.com/docs/rke/latest/en/example-yamls/).
|
||||
|
||||
## How do I check if my certificate chain is valid?
|
||||
|
||||
Use the `openssl verify` command to validate your certificate chain:
|
||||
|
||||
:::tip
|
||||
Configure `SSL_CERT_DIR` and `SSL_CERT_FILE` to a dummy location to make sure the OS installed certificates are not used when verifying manually.
|
||||
:::
|
||||
|
||||
```
|
||||
SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem
|
||||
rancher.yourdomain.com.pem: OK
|
||||
```
|
||||
|
||||
If you receive the error `unable to get local issuer certificate`, the chain is incomplete. This usually means that there is an intermediate CA certificate that issued your server certificate. If you already have this certificate, you can use it in the verification of the certificate like shown below:
|
||||
|
||||
```
|
||||
SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem
|
||||
rancher.yourdomain.com.pem: OK
|
||||
```
|
||||
|
||||
If you have successfully verified your certificate chain, you should include needed intermediate CA certificates in the server certificate to complete the certificate chain for any connection made to Rancher (for example, by the Rancher agent). The order of the certificates in the server certificate file should be first the server certificate itself (contents of `rancher.yourdomain.com.pem`), followed by intermediate CA certificate(s) (contents of `intermediate.pem`).
|
||||
|
||||
```
|
||||
-----BEGIN CERTIFICATE-----
|
||||
%YOUR_CERTIFICATE%
|
||||
-----END CERTIFICATE-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
%YOUR_INTERMEDIATE_CERTIFICATE%
|
||||
-----END CERTIFICATE-----
|
||||
```
|
||||
|
||||
If you still get errors during verification, you can retrieve the subject and the issuer of the server certificate using the following command:
|
||||
|
||||
```
|
||||
openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem
|
||||
subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com
|
||||
issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA
|
||||
```
|
||||
|
||||
## How do I check `Common Name` and `Subject Alternative Names` in my server certificate?
|
||||
|
||||
Although technically an entry in `Subject Alternative Names` is required, having the hostname in both `Common Name` and as entry in `Subject Alternative Names` gives you maximum compatibility with older browser/applications.
|
||||
|
||||
Check `Common Name`:
|
||||
|
||||
```
|
||||
openssl x509 -noout -subject -in cert.pem
|
||||
subject= /CN=rancher.my.org
|
||||
```
|
||||
|
||||
Check `Subject Alternative Names`:
|
||||
|
||||
```
|
||||
openssl x509 -noout -in cert.pem -text | grep DNS
|
||||
DNS:rancher.my.org
|
||||
```
|
||||
|
||||
## Why does it take 5+ minutes for a pod to be rescheduled when a node has failed?
|
||||
|
||||
This is due to a combination of the following default Kubernetes settings:
|
||||
|
||||
* kubelet
|
||||
* `node-status-update-frequency`: Specifies how often kubelet posts node status to master (default 10s)
|
||||
* kube-controller-manager
|
||||
* `node-monitor-period`: The period for syncing NodeStatus in NodeController (default 5s)
|
||||
* `node-monitor-grace-period`: Amount of time which we allow running Node to be unresponsive before marking it unhealthy (default 40s)
|
||||
* `pod-eviction-timeout`: The grace period for deleting pods on failed nodes (default 5m0s)
|
||||
|
||||
See [Kubernetes: kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) and [Kubernetes: kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) for more information on these settings.
|
||||
|
||||
In Kubernetes v1.13, the `TaintBasedEvictions` feature is enabled by default. See [Kubernetes: Taint based Evictions](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/#taint-based-evictions) for more information.
|
||||
|
||||
* kube-apiserver (Kubernetes v1.13 and up)
|
||||
* `default-not-ready-toleration-seconds`: Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration.
|
||||
* `default-unreachable-toleration-seconds`: Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration.
|
||||
|
||||
## Can I use keyboard shortcuts in the UI?
|
||||
|
||||
Yes, most parts of the UI can be reached using keyboard shortcuts. For an overview of the available shortcuts, press `?` anywhere in the UI.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Telemetry FAQ
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/faq/telemetry"/>
|
||||
</head>
|
||||
|
||||
## What is Telemetry?
|
||||
|
||||
Telemetry collects aggregate information about the size of Rancher installations, versions of components used, and which features are used. This information is used by Rancher Labs to help make the product better and is not shared with third-parties.
|
||||
|
||||
## What information is collected?
|
||||
|
||||
No specific identifying information like usernames, passwords, or the names or addresses of user resources will ever be collected.
|
||||
|
||||
The primary things collected include:
|
||||
|
||||
- Aggregate counts (smallest, average, largest, total) of nodes per-cluster and their size (e.g. CPU cores & RAM).
|
||||
- Aggregate counts of logical resources like Clusters, Projects, Namespaces, and Pods.
|
||||
- Counts of what driver was used to deploy clusters and nodes (e.g. GKE vs EC2 vs Imported vs Custom).
|
||||
- Versions of Kubernetes components, Operating Systems and Docker that are deployed on nodes.
|
||||
- Whether some optional components are enabled or not (e.g. which auth providers are used).
|
||||
- The image name & version of Rancher that is running.
|
||||
- A unique randomly-generated identifier for this installation.
|
||||
|
||||
## Can I see the information that is being sent?
|
||||
|
||||
If Telemetry is enabled, you can go to `https://<your rancher server>/v1-telemetry` in your installation to see the current data.
|
||||
|
||||
If Telemetry is not enabled, the process that collects the data is not running, so there is nothing being collected to look at.
|
||||
|
||||
## How do I turn it on or off?
|
||||
|
||||
After initial setup, an administrator can go to the `Settings` page in the `Global` section of the UI and click Edit to change the `telemetry-opt` setting to either `in` or `out`.
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
title: Questions about Upgrading to Rancher v2.x
|
||||
---
|
||||
|
||||
This page contains frequently asked questions about the changes between Rancher v1.x and v2.x, and how to upgrade from Rancher v1.x to v2.x.
|
||||
|
||||
## Kubernetes
|
||||
|
||||
**What does it mean when you say Rancher v2.x is built on Kubernetes?**
|
||||
|
||||
Rancher v2.x is a complete container management platform built 100% on Kubernetes leveraging its Custom Resource and Controller framework. All features are written as a CustomResourceDefinition (CRD) which extends the existing Kubernetes API and can leverage native features such as RBAC.
|
||||
|
||||
<br/>
|
||||
|
||||
**Do you plan to implement upstream Kubernetes, or continue to work on your own fork?**
|
||||
|
||||
We're still going to provide our distribution when you select the default option of having us create your Kubernetes cluster, but it will be very close to upstream.
|
||||
|
||||
<br/>
|
||||
|
||||
**Does this release mean that we need to re-train our support staff in Kubernetes?**
|
||||
|
||||
Yes. Rancher will offer the native Kubernetes functionality via `kubectl` but will also offer our own UI dashboard to allow you to deploy Kubernetes workload without having to understand the full complexity of Kubernetes. However, to fully leverage Kubernetes, we do recommend understanding Kubernetes. We do plan on improving our UX with subsequent releases to make Kubernetes easier to use.
|
||||
|
||||
<br/>
|
||||
|
||||
**Is a Rancher compose going to make a Kubernetes pod? Do we have to learn both now? We usually use the filesystem layer of files, not the UI.**
|
||||
|
||||
No. Unfortunately, the differences were enough such that we cannot support Rancher compose anymore in 2.x. We will be providing both a tool and guides to help with this migration.
|
||||
|
||||
<br/>
|
||||
|
||||
**If we use Kubernetes native YAML files for creating resources, should we expect that to work as expected, or do we need to use Rancher/Docker compose files to deploy infrastructure?**
|
||||
|
||||
Absolutely.
|
||||
|
||||
## Cattle
|
||||
|
||||
**How does Rancher v2.x affect Cattle?**
|
||||
|
||||
Cattle will not supported in v2.x as Rancher has been re-architected to be based on Kubernetes. You can, however, expect majority of Cattle features you use will exist and function similarly on Kubernetes. We will develop migration tools in Rancher v2.1 to help you transform your existing Rancher Compose files into Kubernetes YAML files.
|
||||
|
||||
<br/>
|
||||
|
||||
**Can I migrate existing Cattle workloads into Kubernetes?**
|
||||
|
||||
Yes. In the upcoming Rancher v2.1 release we will provide a tool to help translate existing Cattle workloads in Compose format to Kubernetes YAML format. You will then be able to deploy those workloads on the v2.x platform.
|
||||
|
||||
## Feature Changes
|
||||
|
||||
**Can we still add our own infrastructure services, which had a separate view/filter in 1.6.x?**
|
||||
|
||||
Yes. You can manage Kubernetes storage, networking, and its vast ecosystem of add-ons.
|
||||
|
||||
<br/>
|
||||
|
||||
**Are there changes to default roles available now or going forward? Will the Kubernetes alignment impact plans for roles/RBAC?**
|
||||
|
||||
The default roles will be expanded to accommodate the new Rancher 2.x features, and will also take advantage of the Kubernetes RBAC (Role-Based Access Control) capabilities to give you more flexibility.
|
||||
|
||||
<br/>
|
||||
|
||||
**Will there be any functions like network policies to separate a front-end container from a back-end container through some kind of firewall in v2.x?**
|
||||
|
||||
Yes. You can do so by leveraging Kubernetes' network policies.
|
||||
|
||||
<br/>
|
||||
|
||||
**What about the CLI? Will that work the same way with the same features?**
|
||||
|
||||
Yes. Definitely.
|
||||
|
||||
## Environments & Clusters
|
||||
|
||||
**Can I still create templates for environments and clusters?**
|
||||
|
||||
Starting with 2.0, the concept of an environment has now been changed to a Kubernetes cluster as going forward, only the Kubernetes orchestration engine is supported.
|
||||
|
||||
Kubernetes RKE Templates is on our roadmap for 2.x. Please refer to our Release Notes and documentation for all the features that we currently support.
|
||||
|
||||
<br/>
|
||||
|
||||
**Can you still add an existing host to an environment? (i.e. not provisioned directly from Rancher)**
|
||||
|
||||
Yes. We still provide you with the same way of executing our Rancher agents directly on hosts.
|
||||
|
||||
## Upgrading/Migrating
|
||||
|
||||
**How would the migration from v1.x to v2.x work?**
|
||||
|
||||
Due to the technical difficulty in transforming a Docker container into a pod running Kubernetes, upgrading will require users to "replay" those workloads from v1.x into new v2.x environments. We plan to ship with a tool in v2.1 to translate existing Rancher Compose files into Kubernetes YAML files. You will then be able to deploy those workloads on the v2.x platform.
|
||||
|
||||
<br/>
|
||||
|
||||
**Is it possible to upgrade from Rancher v1.x to v2.x without any disruption to Cattle and Kubernetes clusters?**
|
||||
|
||||
At this time, we are still exploring this scenario and taking feedback. We anticipate that you will need to launch a new Rancher instance and then relaunch on v2.x. Once you've moved to v2.x, upgrades will be in place, as they are in v1.6.
|
||||
|
||||
## Support
|
||||
|
||||
**Are you planning some long-term support releases for Rancher v1.6?**
|
||||
|
||||
That is definitely the focus of the v1.6 stream. We're continuing to improve that release, fix bugs, and maintain it. New releases of the v1.6 stream are announced in the [Rancher forums.](https://forums.rancher.com/c/announcements) The Rancher wiki contains the [v1.6 release notes.](https://github.com/rancher/rancher/wiki/Rancher-1.6)
|
||||
@@ -1,9 +0,0 @@
|
||||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
To get up and running with Rancher quickly, we have included a **Getting Started** section.
|
||||
|
||||
The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.
|
||||
|
||||
Please see the [introduction](getting-started/introduction/introduction.md), [quick start guides](getting-started/quick-start-guides/quick-start-guides.md), and the [installation and upgrade](getting-started/installation-and-upgrade/installation-and-upgrade.md) sections for more.
|
||||
-9
@@ -1,9 +0,0 @@
|
||||
---
|
||||
title: Advanced
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/advanced-user-guides"/>
|
||||
</head>
|
||||
|
||||
The documents in this section contain resources for less common use cases.
|
||||
-38
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Installing Rancher in an Air Gapped Environment with Helm 2
|
||||
---
|
||||
|
||||
> After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.
|
||||
>
|
||||
> If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> This section provides a copy of the older instructions for installing Rancher on a Kubernetes cluster using Helm 2 in an air air gap environment, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
This section is about installations of Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
Throughout the installations instructions, there will be _tabs_ for either a high availability Kubernetes installation or a single-node Docker installation.
|
||||
|
||||
### Air Gapped Kubernetes Installations
|
||||
|
||||
This section covers how to install Rancher on a Kubernetes cluster in an air gapped environment.
|
||||
|
||||
A Kubernetes installation is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
### Air Gapped Docker Installations
|
||||
|
||||
These instructions also cover how to install Rancher on a single node in an air gapped environment.
|
||||
|
||||
The Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.
|
||||
|
||||
Instead of running the Docker installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
- [1. Prepare your Node(s)](../../../other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md)
|
||||
- [2. Collect and Publish Images to your Private Registry](../../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)
|
||||
- [3. Launch a Kubernetes Cluster with RKE](../../../other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md)
|
||||
- [4. Install Rancher](../../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
|
||||
### [Next: Prepare your Node(s)](../../../other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.md)
|
||||
-340
@@ -1,340 +0,0 @@
|
||||
---
|
||||
title: 4. Install Rancher
|
||||
---
|
||||
|
||||
This section is about how to deploy Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are _tabs_ for either a high availability (recommended) or a Docker installation.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install (Recommended)">
|
||||
|
||||
Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes Installation is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
### A. Add the Helm Chart Repository
|
||||
|
||||
From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.
|
||||
|
||||
1. If you haven't already, initialize Helm locally on a workstation that has internet access.
|
||||
|
||||
:::note
|
||||
|
||||
Refer to the [Helm version requirements](../../../resources/choose-a-rancher-version.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
:::
|
||||
|
||||
```plain
|
||||
helm init -c
|
||||
```
|
||||
|
||||
2. Use the `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Version of Rancher](../../../resources/choose-a-rancher-version.md).
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a `.tgz` file.
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
|
||||
> Want additional options? See the Rancher [Helm chart options](../../../../../reference-guides/installation-references/helm-chart-options.md).
|
||||
|
||||
### B. Choose your SSL Configuration
|
||||
|
||||
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
| Configuration | Chart option | Description | Requires cert-manager |
|
||||
| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/> This is the **default** and does not need to be added when rendering the Helm template. | yes |
|
||||
| Certificates from Files | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s). <br/> This option must be passed when rendering the Rancher Helm template. | no |
|
||||
|
||||
### C. Render the Rancher Helm Template
|
||||
|
||||
When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.
|
||||
|
||||
| Chart Option | Chart Value | Description |
|
||||
| ----------------------- | -------------------------------- | ---- |
|
||||
| `certmanager.version` | `<version>` | Configure proper Rancher TLS issuer depending of running cert-manager version. |
|
||||
| `systemDefaultRegistry` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. 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. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ |
|
||||
|
||||
Based on the choice your made in [B. Choose your SSL Configuration](#b-choose-your-ssl-configuration), complete one of the procedures below.
|
||||
|
||||
<details id="self-signed">
|
||||
<summary>Option A-Default Self-Signed Certificate</summary>
|
||||
|
||||
By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
> **Note:**
|
||||
> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation](../../../resources/upgrade-cert-manager.md).
|
||||
|
||||
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.14.2
|
||||
```
|
||||
|
||||
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.
|
||||
```plain
|
||||
helm template ./cert-manager-v0.14.2.tgz --output-dir . \
|
||||
--name cert-manager --namespace cert-manager \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector
|
||||
```
|
||||
|
||||
1. Download the required CRD file for cert-manager
|
||||
```plain
|
||||
curl -L -o cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.14/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details id="secret">
|
||||
<summary>Option B: Certificates From Files using Kubernetes Secrets</summary>
|
||||
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.
|
||||
|
||||
Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------- |
|
||||
| `<VERSION>` | The version number of the output tarball. |
|
||||
| `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry. |
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
Then refer to [Adding TLS Secrets](../../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
</details>
|
||||
|
||||
### D. Install Rancher
|
||||
|
||||
Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.
|
||||
|
||||
Use `kubectl` to create namespaces and apply the rendered manifests.
|
||||
|
||||
If you choose to use self-signed certificates in [B. Choose your SSL Configuration](#b-choose-your-ssl-configuration), install cert-manager.
|
||||
|
||||
<details id="install-cert-manager">
|
||||
<summary>Self-Signed Certificate Installs - Install Cert-manager</summary>
|
||||
|
||||
If you are using self-signed certificates, install cert-manager:
|
||||
|
||||
1. Create the namespace for cert-manager.
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Create the cert-manager CustomResourceDefinitions (CRDs).
|
||||
```plain
|
||||
kubectl apply -f cert-manager/cert-manager-crd.yaml
|
||||
```
|
||||
|
||||
> **Important:**
|
||||
> If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
|
||||
|
||||
1. Launch cert-manager.
|
||||
```plain
|
||||
kubectl apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
Install Rancher:
|
||||
|
||||
```plain
|
||||
kubectl create namespace cattle-system
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
**Step Result:** If you are installing Rancher v2.3.0+, the installation is complete.
|
||||
|
||||
### E. For Rancher versions before v2.3.0, Configure System Charts
|
||||
|
||||
If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in GitHub, an air gapped installation will not be able to access these charts. Therefore, you must [configure the Rancher system charts](../../../resources/local-system-charts.md).
|
||||
|
||||
### Additional Resources
|
||||
|
||||
These resources could be helpful when installing Rancher:
|
||||
|
||||
- [Rancher Helm chart options](../../../../../reference-guides/installation-references/helm-chart-options.md)
|
||||
- [Adding TLS secrets](../../../resources/add-tls-secrets.md)
|
||||
- [Troubleshooting Rancher Kubernetes Installations](../../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
The Docker installation is for Rancher users that are wanting to **test** out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. **Important: If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker installation to a Kubernetes Installation.** Instead of running the single node installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
| Environment Variable Key | Environment Variable Value | Description |
|
||||
| -------------------------------- | -------------------------------- | ---- |
|
||||
| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. 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. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ |
|
||||
|
||||
> **Do you want to...**
|
||||
>
|
||||
> - Configure custom CA root certificate to access your services? See [Custom CA root certificate](../../../../../reference-guides/installation-references/helm-chart-options.md#additional-trusted-cas).
|
||||
> - Record all transactions with the Rancher API? See [API Auditing](../../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log).
|
||||
|
||||
- For Rancher before v2.3.0, you will need to mirror the `system-charts` repository to a location in your network that Rancher can reach. Then, after Rancher is installed, you will need to configure Rancher to use that repository. For details, refer to the documentation on [setting up the system charts for Rancher before v2.3.0.](../../../resources/local-system-charts.md)
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A-Default Self-Signed Certificate</summary>
|
||||
|
||||
If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.
|
||||
|
||||
Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../resources/choose-a-rancher-version.md) that you want to install. |
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B-Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.
|
||||
|
||||
> **Prerequisites:**
|
||||
> From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice.
|
||||
>
|
||||
> - The certificate files must be in PEM format.
|
||||
> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
| `<CA_CERTS>` | The path to the certificate authority's certificate. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../resources/choose-a-rancher-version.md) that you want to install. |
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
<details id="option-c">
|
||||
<summary>Option C-Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.
|
||||
|
||||
> **Prerequisite:** The certificate files must be in PEM format.
|
||||
|
||||
After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../resources/choose-a-rancher-version.md) that you want to install. |
|
||||
|
||||
> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
--no-cacerts \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
If you are installing Rancher v2.3.0+, the installation is complete.
|
||||
|
||||
If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in GitHub, an air gapped installation will not be able to access these charts. Therefore, you must [configure the Rancher system charts](../../../resources/local-system-charts.md).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
-83
@@ -1,83 +0,0 @@
|
||||
---
|
||||
title: '3. Install Kubernetes with RKE (Kubernetes Installs Only)'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes"/>
|
||||
</head>
|
||||
|
||||
This section is about how to prepare to launch a Kubernetes cluster which is used to deploy Rancher server for your air gapped environment.
|
||||
|
||||
Since a Kubernetes Installation requires a Kubernetes cluster, we will create a Kubernetes cluster using [Rancher Kubernetes Engine](https://rancher.com/docs/rke/latest/en/) (RKE). Before being able to start your Kubernetes cluster, you'll need to [install RKE](https://rancher.com/docs/rke/latest/en/installation/) and create a RKE config file.
|
||||
|
||||
- [A. Create an RKE Config File](#a-create-an-rke-config-file)
|
||||
- [B. Run RKE](#b-run-rke)
|
||||
- [C. Save Your Files](#c-save-your-files)
|
||||
|
||||
### A. Create an RKE Config File
|
||||
|
||||
From a system that can access ports 22/tcp and 6443/tcp on your host nodes, use the sample below to create a new file named `rancher-cluster.yml`. This file is a Rancher Kubernetes Engine configuration file (RKE config file), which is a configuration for the cluster you're deploying Rancher to.
|
||||
|
||||
Replace values in the code sample below with help of the _RKE Options_ table. Use the IP address or DNS names of the [3 nodes](./prepare-nodes.md) you created.
|
||||
|
||||
> **Tip:** For more details on the options available, see the RKE [Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
<figcaption>RKE Options</figcaption>
|
||||
|
||||
| Option | Required | Description |
|
||||
| ------------------ | -------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `address` | ✓ | The DNS or IP address for the node within the air gap network. |
|
||||
| `user` | ✓ | A user that can run docker commands. |
|
||||
| `role` | ✓ | List of Kubernetes roles assigned to the node. |
|
||||
| `internal_address` | optional<sup>1</sup> | The DNS or IP address used for internal cluster traffic. |
|
||||
| `ssh_key_path` | | Path to SSH private key used to authenticate to the node (defaults to `~/.ssh/id_rsa`). |
|
||||
|
||||
> <sup>1</sup> Some services like AWS EC2 require setting the `internal_address` if you want to use self-referencing security groups or firewalls.
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: 10.10.3.187 # node air gap network IP
|
||||
internal_address: 172.31.7.22 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.254 # node air gap network IP
|
||||
internal_address: 172.31.13.132 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.89 # node air gap network IP
|
||||
internal_address: 172.31.3.216 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
|
||||
private_registries:
|
||||
- url: <REGISTRY.YOURDOMAIN.COM:PORT> # private registry url
|
||||
user: rancher
|
||||
password: '*********'
|
||||
is_default: true
|
||||
```
|
||||
|
||||
### B. Run RKE
|
||||
|
||||
After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
|
||||
|
||||
```
|
||||
rke up --config ./rancher-cluster.yml
|
||||
```
|
||||
|
||||
### C. Save Your Files
|
||||
|
||||
> **Important**
|
||||
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
|
||||
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_rancher-cluster.yml`: The [Kubeconfig file](https://rancher.com/docs/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](https://rancher.com/docs/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.
|
||||
|
||||
### [Next: Install Rancher](../../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
-274
@@ -1,274 +0,0 @@
|
||||
---
|
||||
title: '2. Collect and Publish Images to your Private Registry'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images"/>
|
||||
</head>
|
||||
|
||||
> **Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use.
|
||||
>
|
||||
> **Note:** Populating the private registry with images is the same process for HA and Docker installations, the differences in this section is based on whether or not you are planning to provision a Windows cluster or not.
|
||||
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gap installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
|
||||
This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.
|
||||
|
||||
By default, we provide the steps of how to populate your private registry assuming you are provisioning Linux only clusters, but if you plan on provisioning any [Windows clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/use-windows-clusters.md), there are separate instructions to support the images needed for a Windows cluster.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Linux Only Clusters">
|
||||
|
||||
For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.
|
||||
|
||||
A. Find the required assets for your Rancher version <br/>
|
||||
B. Collect all the required images <br/>
|
||||
C. Save the images to your workstation <br/>
|
||||
D. Populate the private registry
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
### A. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. Click **Assets*.*
|
||||
|
||||
2. From the release's **Assets** section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
| ---------------- | -------------- |
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
### B. Collect all the required images (For Kubernetes Installs using Rancher Generated Self-Signed Certificate)
|
||||
|
||||
In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../../resources/upgrade-cert-manager.md/).
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v0.14.2
|
||||
helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
### C. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
### D. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images. The `rancher-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push `rancher-images.txt` and `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Linux and Windows Clusters">
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests.
|
||||
|
||||
### Windows Steps
|
||||
|
||||
The Windows images need to be collected and pushed from a Windows server workstation.
|
||||
|
||||
A. Find the required assets for your Rancher version <br/>
|
||||
B. Save the images to your Windows Server workstation <br/>
|
||||
C. Prepare the Docker daemon <br/>
|
||||
D. Populate the private registry
|
||||
|
||||
<details>
|
||||
<summary>Collecting and Populating Windows Images into the Private Registry"%}}</summary>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Windows Server 1809 workstation that has internet access, access to your private registry, and at least 50 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
Your registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
### A. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's "Assets" section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
|------------------------|-------------------|
|
||||
| `rancher-windows-images.txt` | This file contains a list of Windows images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.ps1` | This script pulls all the images in the `rancher-windows-images.txt` from Docker Hub and saves all of the images as `rancher-windows-images.tar.gz`. |
|
||||
| `rancher-load-images.ps1` | This script loads the images from the `rancher-windows-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
### B. Save the images to your Windows Server workstation
|
||||
|
||||
1. Using `powershell`, go to the directory that has the files that were downloaded in the previous step.
|
||||
|
||||
1. Run `rancher-save-images.ps1` to create a tarball of all the required images:
|
||||
|
||||
```plain
|
||||
./rancher-save-images.ps1
|
||||
```
|
||||
|
||||
**Step Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
### C. Prepare the Docker daemon
|
||||
|
||||
Append your private registry address to the `allow-nondistributable-artifacts` config field in the Docker daemon (`C:\ProgramData\Docker\config\daemon.json`). Since the base image of Windows images are maintained by the `mcr.microsoft.com` registry, this step is required as the layers in the Microsoft registry are missing from Docker Hub and need to be pulled into the private registry.
|
||||
|
||||
```
|
||||
{
|
||||
...
|
||||
"allow-nondistributable-artifacts": [
|
||||
...
|
||||
"<REGISTRY.YOURDOMAIN.COM:PORT>"
|
||||
]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### D. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-windows-images.tar.gz` to your private registry using the scripts to load the images. The `rancher-windows-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.ps1` script.
|
||||
|
||||
1. Using `powershell`, log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Using `powershell`, use `rancher-load-images.ps1` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.ps1 --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Linux Steps
|
||||
|
||||
The Linux images needs to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images.
|
||||
|
||||
A. Find the required assets for your Rancher version <br/>
|
||||
B. Collect all the required images <br/>
|
||||
C. Save the images to your Linux workstation <br/>
|
||||
D. Populate the private registry
|
||||
|
||||
<details>
|
||||
<summary>Collecting and Populating Linux Images into the Private Registry</summary>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
You must populate the private registry with the Windows images before populating the private registry with Linux images. If you have already populated the registry with Linux images, you will need to follow these instructions again as they will publish manifests that support Windows and Linux images.
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
### A. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's **Assets** section, download the following files, which are required to install Rancher in an air gap environment:
|
||||
|
||||
| Release File | Description |
|
||||
|----------------------------|------|
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-windows-images.txt` | This file contains a list of images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
### B. Collect all the required images
|
||||
|
||||
**For Kubernetes Installs using Rancher Generated Self-Signed Certificate:** In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../../resources/upgrade-cert-manager.md).
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v0.14.2
|
||||
helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
### C. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
### D. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the `rancher-load-images.sh script` to load the images. The `rancher-images.txt` / `rancher-windows-images.txt` image list is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt \
|
||||
--windows-image-list ./rancher-windows-images.txt \
|
||||
--registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### [Next: Kubernetes Installs - Launch a Kubernetes Cluster with RKE](../../../other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.md)
|
||||
|
||||
### [Next: Docker Installs - Install Rancher](../../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
-107
@@ -1,107 +0,0 @@
|
||||
---
|
||||
title: '1. Prepare your Node(s)'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry"/>
|
||||
</head>
|
||||
|
||||
This section is about how to prepare your node(s) to install Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are _tabs_ for either a high availability (recommended) or a Docker installation.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install (Recommended)">
|
||||
|
||||
### OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../installation-requirements/installation-requirements.md)
|
||||
|
||||
### Private Registry
|
||||
|
||||
Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [Docker documentation](https://docs.docker.com/registry/).
|
||||
|
||||
### CLI Tools
|
||||
|
||||
The following CLI tools are required for the Kubernetes Install. Make sure these tools are installed on your workstation and available in your `$PATH`.
|
||||
|
||||
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
|
||||
- [rke](https://rancher.com/docs/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters.
|
||||
- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](../../../resources/choose-a-rancher-version.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
### OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node(s) fulfill the general [installation requirements.](../../../installation-requirements/installation-requirements.md)
|
||||
|
||||
### Private Registry
|
||||
|
||||
Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [Docker documentation](https://docs.docker.com/registry/).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Set up Infrastructure
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install (Recommended)">
|
||||
|
||||
Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
### 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>Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at ingress controllers</figcaption>
|
||||
|
||||
|
||||
|
||||
### A. Provision three air gapped Linux hosts according to our requirements
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
### B. Set up your Load Balancer
|
||||
|
||||
When setting up the Kubernetes cluster that will run the Rancher server components, an Ingress controller pod will be deployed on each of your nodes. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server.
|
||||
|
||||
You will need to configure a load balancer as a basic Layer 4 TCP forwarder to direct traffic to these ingress controller pods. The exact configuration will vary depending on your environment.
|
||||
|
||||
> **Important:**
|
||||
> Only use this load balancer (i.e, the `local` cluster Ingress) to load balance the Rancher server. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps.
|
||||
|
||||
**Load Balancer Configuration Samples:**
|
||||
|
||||
- For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)
|
||||
- For an example showing how to set up an Amazon NLB load balancer, refer to [this page.](../../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
The Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker installation to a Kubernetes Installation.
|
||||
|
||||
Instead of running the Docker installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.
|
||||
|
||||
### A. Provision a single, air gapped Linux host according to our Requirements
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
View hardware and software requirements for each of your cluster nodes in [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### [Next: Collect and Publish Images to your Private Registry](../../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md)
|
||||
-5
@@ -1,5 +0,0 @@
|
||||
---
|
||||
title: cluster.yml Templates for RKE add-on installs
|
||||
---
|
||||
|
||||
These templates are intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
-161
@@ -1,161 +0,0 @@
|
||||
---
|
||||
title: Template for an RKE Cluster with a Certificate Signed by Recognized CA and a Layer 4 Load Balancer
|
||||
---
|
||||
|
||||
RKE uses a cluster.yml file to install and configure your Kubernetes cluster.
|
||||
|
||||
This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
|
||||
The following template can be used for the cluster.yml if you have a setup with:
|
||||
|
||||
- Certificate signed by a recognized CA
|
||||
- Layer 4 load balancer
|
||||
- [NGINX Ingress controller](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
> For more options, refer to [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: <IP> # hostname or IP to access nodes
|
||||
user: <USER> # root user (usually 'root')
|
||||
role: [controlplane,etcd,worker] # K8s roles for node
|
||||
ssh_key_path: <PEM_FILE> # path to PEM file
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
|
||||
addons: |-
|
||||
---
|
||||
kind: Namespace
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-system
|
||||
---
|
||||
kind: ServiceAccount
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
---
|
||||
kind: ClusterRoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
name: cattle-crb
|
||||
namespace: cattle-system
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: cluster-admin
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: <BASE64_CRT> # ssl cert for ingress. If self-signed, must be signed by same CA as cattle server
|
||||
tls.key: <BASE64_KEY> # ssl key for ingress. If self-signed, must be signed by same CA as cattle server
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-service
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
protocol: TCP
|
||||
name: http
|
||||
- port: 443
|
||||
targetPort: 443
|
||||
protocol: TCP
|
||||
name: https
|
||||
selector:
|
||||
app: cattle
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: <FQDN> # FQDN to access cattle server
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
tls:
|
||||
- secretName: cattle-keys-ingress
|
||||
hosts:
|
||||
- <FQDN> # FQDN to access cattle server
|
||||
---
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
# Rancher install via RKE addons is only supported up to v2.0.8
|
||||
- image: rancher/rancher:v2.0.8
|
||||
args:
|
||||
- --no-cacerts
|
||||
imagePullPolicy: Always
|
||||
name: cattle-server
|
||||
# env:
|
||||
# - name: HTTP_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: HTTPS_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: NO_PROXY
|
||||
# value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 60
|
||||
periodSeconds: 60
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 20
|
||||
periodSeconds: 10
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
- containerPort: 443
|
||||
protocol: TCP
|
||||
```
|
||||
-177
@@ -1,177 +0,0 @@
|
||||
---
|
||||
title: Template for an RKE Cluster with a Self-signed Certificate and Layer 4 Load Balancer
|
||||
---
|
||||
|
||||
RKE uses a cluster.yml file to install and configure your Kubernetes cluster.
|
||||
|
||||
This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
|
||||
The following template can be used for the cluster.yml if you have a setup with:
|
||||
|
||||
- Self-signed SSL
|
||||
- Layer 4 load balancer
|
||||
- [NGINX Ingress controller](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
> For more options, refer to [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: <IP> # hostname or IP to access nodes
|
||||
user: <USER> # root user (usually 'root')
|
||||
role: [controlplane,etcd,worker] # K8s roles for node
|
||||
ssh_key_path: <PEM_FILE> # path to PEM file
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
|
||||
addons: |-
|
||||
---
|
||||
kind: Namespace
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-system
|
||||
---
|
||||
kind: ServiceAccount
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
---
|
||||
kind: ClusterRoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
name: cattle-crb
|
||||
namespace: cattle-system
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: cluster-admin
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: <BASE64_CRT> # ssl cert for ingress. If selfsigned, must be signed by same CA as cattle server
|
||||
tls.key: <BASE64_KEY> # ssl key for ingress. If selfsigned, must be signed by same CA as cattle server
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: <BASE64_CA> # CA cert used to sign cattle server cert and key
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-service
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
protocol: TCP
|
||||
name: http
|
||||
- port: 443
|
||||
targetPort: 443
|
||||
protocol: TCP
|
||||
name: https
|
||||
selector:
|
||||
app: cattle
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: <FQDN> # FQDN to access cattle server
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
tls:
|
||||
- secretName: cattle-keys-ingress
|
||||
hosts:
|
||||
- <FQDN> # FQDN to access cattle server
|
||||
---
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
# Rancher install via RKE addons is only supported up to v2.0.8
|
||||
- image: rancher/rancher:v2.0.8
|
||||
imagePullPolicy: Always
|
||||
name: cattle-server
|
||||
# env:
|
||||
# - name: HTTP_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: HTTPS_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: NO_PROXY
|
||||
# value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 60
|
||||
periodSeconds: 60
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 20
|
||||
periodSeconds: 10
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
- containerPort: 443
|
||||
protocol: TCP
|
||||
volumeMounts:
|
||||
- mountPath: /etc/rancher/ssl
|
||||
name: cattle-keys-volume
|
||||
readOnly: true
|
||||
volumes:
|
||||
- name: cattle-keys-volume
|
||||
secret:
|
||||
defaultMode: 420
|
||||
secretName: cattle-keys-server
|
||||
```
|
||||
-157
@@ -1,157 +0,0 @@
|
||||
---
|
||||
title: Template for an RKE Cluster with a Self-signed Certificate and SSL Termination on Layer 7 Load Balancer
|
||||
---
|
||||
|
||||
RKE uses a cluster.yml file to install and configure your Kubernetes cluster.
|
||||
|
||||
This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
|
||||
The following template can be used for the cluster.yml if you have a setup with:
|
||||
|
||||
- Layer 7 load balancer with self-signed SSL termination (HTTPS)
|
||||
- [NGINX Ingress controller](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
> For more options, refer to [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: <IP> # hostname or IP to access nodes
|
||||
user: <USER> # root user (usually 'root')
|
||||
role: [controlplane,etcd,worker] # K8s roles for node
|
||||
ssh_key_path: <PEM_FILE> # path to PEM file
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
|
||||
addons: |-
|
||||
---
|
||||
kind: Namespace
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-system
|
||||
---
|
||||
kind: ServiceAccount
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
---
|
||||
kind: ClusterRoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
name: cattle-crb
|
||||
namespace: cattle-system
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: cluster-admin
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: <BASE64_CA> # CA cert used to sign cattle server cert and key
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-service
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: cattle
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/ssl-redirect: "false" # Disable redirect to ssl
|
||||
spec:
|
||||
rules:
|
||||
- host: <FQDN>
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
---
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
# Rancher install via RKE addons is only supported up to v2.0.8
|
||||
- image: rancher/rancher:v2.0.8
|
||||
imagePullPolicy: Always
|
||||
name: cattle-server
|
||||
# env:
|
||||
# - name: HTTP_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: HTTPS_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: NO_PROXY
|
||||
# value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 60
|
||||
periodSeconds: 60
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 20
|
||||
periodSeconds: 10
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
volumeMounts:
|
||||
- mountPath: /etc/rancher/ssl
|
||||
name: cattle-keys-volume
|
||||
readOnly: true
|
||||
volumes:
|
||||
- name: cattle-keys-volume
|
||||
secret:
|
||||
defaultMode: 420
|
||||
secretName: cattle-keys-server
|
||||
```
|
||||
-141
@@ -1,141 +0,0 @@
|
||||
---
|
||||
title: Template for an RKE Cluster with a Recognized CA Certificate and SSL Termination on Layer 7 Load Balancer
|
||||
---
|
||||
|
||||
RKE uses a cluster.yml file to install and configure your Kubernetes cluster.
|
||||
|
||||
This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.
|
||||
|
||||
The following template can be used for the cluster.yml if you have a setup with:
|
||||
|
||||
- Layer 7 load balancer with SSL termination (HTTPS)
|
||||
- [NGINX Ingress controller](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
> For more options, refer to [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: <IP> # hostname or IP to access nodes
|
||||
user: <USER> # root user (usually 'root')
|
||||
role: [controlplane,etcd,worker] # K8s roles for node
|
||||
ssh_key_path: <PEM_FILE> # path to PEM file
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
|
||||
addons: |-
|
||||
---
|
||||
kind: Namespace
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-system
|
||||
---
|
||||
kind: ServiceAccount
|
||||
apiVersion: v1
|
||||
metadata:
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
---
|
||||
kind: ClusterRoleBinding
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
metadata:
|
||||
name: cattle-crb
|
||||
namespace: cattle-system
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: cattle-admin
|
||||
namespace: cattle-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: cluster-admin
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-service
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 80
|
||||
protocol: TCP
|
||||
name: http
|
||||
selector:
|
||||
app: cattle
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/ssl-redirect: "false" # Disable redirect to ssl
|
||||
spec:
|
||||
rules:
|
||||
- host: <FQDN>
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
---
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
# Rancher install via RKE addons is only supported up to v2.0.8
|
||||
- image: rancher/rancher:v2.0.8
|
||||
args:
|
||||
- --no-cacerts
|
||||
imagePullPolicy: Always
|
||||
name: cattle-server
|
||||
# env:
|
||||
# - name: HTTP_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: HTTPS_PROXY
|
||||
# value: "http://your_proxy_address:port"
|
||||
# - name: NO_PROXY
|
||||
# value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 60
|
||||
periodSeconds: 60
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ping
|
||||
port: 80
|
||||
initialDelaySeconds: 20
|
||||
periodSeconds: 10
|
||||
ports:
|
||||
- containerPort: 80
|
||||
protocol: TCP
|
||||
```
|
||||
-244
@@ -1,244 +0,0 @@
|
||||
---
|
||||
title: Docker Install with TLS Termination at Layer-7 NGINX Load Balancer
|
||||
---
|
||||
|
||||
For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction.
|
||||
|
||||
A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.
|
||||
|
||||
This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.
|
||||
|
||||
> **Want to skip the external load balancer?**
|
||||
> See [Docker Installation](../../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) instead.
|
||||
|
||||
## Requirements for OS, Docker, Hardware, and Networking
|
||||
|
||||
Make sure that your node fulfills the general [installation requirements.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
## Installation Outline
|
||||
|
||||
|
||||
## 1. Provision Linux Host
|
||||
|
||||
Provision a single Linux host according to our [Requirements](../../installation-requirements/installation-requirements.md) 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](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md). 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](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
For help troubleshooting certificates, see [this section.](../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### API Auditing
|
||||
|
||||
If you want to record all transactions with the Rancher API, enable the [API Auditing](../../../installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.md) 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](air-gap-helm2/air-gap-helm2.md), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL in front of `rancher/rancher:latest`.
|
||||
|
||||
**Example:**
|
||||
|
||||
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
|
||||
|
||||
### Persistent Data
|
||||
|
||||
Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: `/var/lib/rancher`.
|
||||
|
||||
You can bind mount a host volume to this location to preserve data on the host it is running on:
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /opt/rancher:/var/lib/rancher \
|
||||
rancher/rancher:latest
|
||||
```
|
||||
|
||||
This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).
|
||||
|
||||
> **Note:** This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - TCP and UDP Load Balancer](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/>
|
||||
|
||||
-565
@@ -1,565 +0,0 @@
|
||||
---
|
||||
title: Enabling the API Audit Log to Record System Events
|
||||
---
|
||||
|
||||
You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.
|
||||
|
||||
You can enable API Auditing during Rancher installation or upgrade.
|
||||
|
||||
## Enabling API Audit Log
|
||||
|
||||
The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.
|
||||
|
||||
- [Docker Install](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
|
||||
|
||||
- [Kubernetes Install](../../../../reference-guides/installation-references/helm-chart-options.md#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 |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `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`](#api-audit-log-options) setting.
|
||||
|
||||
| `AUDIT_LEVEL` Setting | Metadata | Request Body | 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
|
||||
```
|
||||
|
||||
#### Rancher Web GUI
|
||||
|
||||
1. From the context menu, select **Cluster: local > System**.
|
||||
1. From the main navigation bar, choose **Resources > Workloads.** (In versions before v2.3.0, choose **Workloads** on the main navigation bar.) Find the `cattle-system` namespace. Open the `rancher` workload by clicking its link.
|
||||
1. Pick one of the `rancher` pods and select **⋮ > View Logs**.
|
||||
1. From the **Logs** drop-down, select `rancher-audit-log`.
|
||||
|
||||
#### Shipping the Audit Log
|
||||
|
||||
You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See [Rancher Tools - Logging](../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: "1. Create Nodes and Load Balancer"
|
||||
---
|
||||
|
||||
Use your provider of choice to provision 3 nodes and a Load Balancer endpoint for your RKE install.
|
||||
|
||||
> **Note:** These nodes must be in the same region/datacenter. You may place these servers in separate availability zones.
|
||||
|
||||
### Node Requirements
|
||||
|
||||
View the supported operating systems and hardware/software/networking requirements for nodes running Rancher at [Node Requirements](../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
View the OS requirements for RKE at [RKE Requirements](https://rancher.com/docs/rke/latest/en/os/)
|
||||
|
||||
### Load Balancer
|
||||
|
||||
RKE will configure an Ingress controller pod, on each of your nodes. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server.
|
||||
|
||||
Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment.
|
||||
|
||||
>**Important:**
|
||||
>Do not use this load balancer (i.e, the `local` cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the `local` cluster to Rancher and no other applications.
|
||||
|
||||
#### Examples
|
||||
|
||||
* [Nginx](nginx.md)
|
||||
* [Amazon NLB](nlb.md)
|
||||
|
||||
### [Next: Install Kubernetes with RKE](../kubernetes-rke/kubernetes-rke.md)
|
||||
-80
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: NGINX
|
||||
---
|
||||
|
||||
NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes.
|
||||
|
||||
>**Note:**
|
||||
> In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX.
|
||||
>
|
||||
> One caveat: do not use one of your Rancher nodes as the load balancer.
|
||||
|
||||
## Install NGINX
|
||||
|
||||
Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are `1.14` and `1.15`. For help installing NGINX, refer to their [install documentation](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](create-nodes-lb.md).
|
||||
|
||||
>**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
|
||||
```
|
||||
-175
@@ -1,175 +0,0 @@
|
||||
---
|
||||
title: Amazon NLB
|
||||
---
|
||||
|
||||
## Objectives
|
||||
|
||||
Configuring an Amazon NLB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
|
||||
|
||||
1. [Create Target Groups](#create-target-groups)
|
||||
|
||||
Begin by creating two target groups for the **TCP** protocol, one regarding TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups.
|
||||
|
||||
2. [Register Targets](#register-targets)
|
||||
|
||||
Add your Linux nodes to the target groups.
|
||||
|
||||
3. [Create Your NLB](#create-your-nlb)
|
||||
|
||||
Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in **1. Create Target Groups**.
|
||||
|
||||
> **Note:** 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 ELB or ALB.
|
||||
|
||||
## Create Target Groups
|
||||
|
||||
Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but its convenient to add a listener for port 80 which will be redirected to port 443 automatically. The NGINX ingress controller on the nodes will make sure that port 80 gets redirected to port 443.
|
||||
|
||||
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.
|
||||
|
||||
The Target Groups configuration resides in the **Load Balancing** section of the **EC2** service. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**.
|
||||
|
||||
|
||||
|
||||
Click **Create target group** to create the first target group, regarding TCP port 443.
|
||||
|
||||
### Target Group (TCP port 443)
|
||||
|
||||
Configure the first target group according to the table below. Screenshots of the configuration are shown just below the table.
|
||||
|
||||
Option | Setting
|
||||
--------------------------------------|------------------------------------
|
||||
Target Group Name | `rancher-tcp-443`
|
||||
Protocol | `TCP`
|
||||
Port | `443`
|
||||
Target type | `instance`
|
||||
VPC | Choose your VPC
|
||||
Protocol<br/>(Health Check) | `HTTP`
|
||||
Path<br/>(Health Check) | `/healthz`
|
||||
Port (Advanced health check) | `override`,`80`
|
||||
Healthy threshold (Advanced health) | `3`
|
||||
Unhealthy threshold (Advanced) | `3`
|
||||
Timeout (Advanced) | `6 seconds`
|
||||
Interval (Advanced) | `10 second`
|
||||
Success codes | `200-399`
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 443 settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 443 Advanced settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
|
||||
Click **Create target group** to create the second target group, regarding TCP port 80.
|
||||
|
||||
### Target Group (TCP port 80)
|
||||
|
||||
Configure the second target group according to the table below. Screenshots of the configuration are shown just below the table.
|
||||
|
||||
Option | Setting
|
||||
--------------------------------------|------------------------------------
|
||||
Target Group Name | `rancher-tcp-80`
|
||||
Protocol | `TCP`
|
||||
Port | `80`
|
||||
Target type | `instance`
|
||||
VPC | Choose your VPC
|
||||
Protocol<br/>(Health Check) | `HTTP`
|
||||
Path<br/>(Health Check) | `/healthz`
|
||||
Port (Advanced health check) | `traffic port`
|
||||
Healthy threshold (Advanced health) | `3`
|
||||
Unhealthy threshold (Advanced) | `3`
|
||||
Timeout (Advanced) | `6 seconds`
|
||||
Interval (Advanced) | `10 second`
|
||||
Success codes | `200-399`
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 80 settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 80 Advanced settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
|
||||
## Register Targets
|
||||
|
||||
Next, add your Linux nodes to both target groups.
|
||||
|
||||
Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**.
|
||||
|
||||
|
||||
|
||||
Select the instances (Linux nodes) you want to add, and click **Add to registered**.
|
||||
|
||||
***
|
||||
**Screenshot Add targets to target group TCP port 443**<br/>
|
||||
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Added targets to target group TCP port 443**<br/>
|
||||
|
||||
|
||||
|
||||
When the instances are added, click **Save** on the bottom right of the screen.
|
||||
|
||||
Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group.
|
||||
|
||||
## Create Your NLB
|
||||
|
||||
Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in [Create Target Groups](#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**.
|
||||
|
||||
5. Complete the **Step 1: Configure Load Balancer** form.
|
||||
- **Basic Configuration**
|
||||
|
||||
- Name: `rancher`
|
||||
- Scheme: `internal` or `internet-facing`
|
||||
|
||||
The Scheme that you choose for your NLB is dependent on the configuration of your instances/VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to `internal` rather than `internet-facing`.
|
||||
- **Listeners**
|
||||
|
||||
Add the **Load Balancer Protocols** and **Load Balancer Ports** below.
|
||||
- `TCP`: `443`
|
||||
|
||||
- **Availability Zones**
|
||||
|
||||
- Select Your **VPC** and **Availability Zones**.
|
||||
|
||||
6. Complete the **Step 2: Configure Routing** form.
|
||||
|
||||
- From the **Target Group** drop-down, choose **Existing target group**.
|
||||
|
||||
- From the **Name** drop-down, choose `rancher-tcp-443`.
|
||||
|
||||
- Open **Advanced health check settings**, and configure **Interval** to `10 seconds`.
|
||||
|
||||
7. Complete **Step 3: Register Targets**. Since you registered your targets earlier, all you have to do is click **Next: Review**.
|
||||
|
||||
8. Complete **Step 4: Review**. Look over the load balancer details and click **Create** when you're satisfied.
|
||||
|
||||
9. After AWS creates the NLB, click **Close**.
|
||||
|
||||
## Add listener to NLB for TCP port 80
|
||||
|
||||
1. Select your newly created NLB and select the **Listeners** tab.
|
||||
|
||||
2. Click **Add listener**.
|
||||
|
||||
3. Use `TCP`:`80` as **Protocol** : **Port**
|
||||
|
||||
4. Click **Add action** and choose **Forward to...**
|
||||
|
||||
5. From the **Forward to** drop-down, choose `rancher-tcp-80`.
|
||||
|
||||
6. Click **Save** in the top right of the screen.
|
||||
-65
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: "Initialize Helm: Install the Tiller Service"
|
||||
description: "With Helm, you can create configurable deployments instead of using static files. In order to use Helm, the Tiller service needs to be installed on your cluster."
|
||||
---
|
||||
|
||||
Helm is the package management tool of choice for Kubernetes. Helm "charts" provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh/). To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster.
|
||||
|
||||
For systems without direct internet access, see [Helm - Air Gap](../../../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) for install details.
|
||||
|
||||
Refer to the [Helm version requirements](../../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
|
||||
|
||||
### Install Tiller on the Cluster
|
||||
|
||||
> **Important:** Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.
|
||||
|
||||
Helm installs the `tiller` service on your cluster to manage charts. Since RKE enables RBAC by default we will need to use `kubectl` to create a `serviceaccount` and `clusterrolebinding` so `tiller` has permission to deploy to the cluster.
|
||||
|
||||
* Create the `ServiceAccount` in the `kube-system` namespace.
|
||||
* Create the `ClusterRoleBinding` to give the `tiller` account access to the cluster.
|
||||
* Finally use `helm` to install the `tiller` service
|
||||
|
||||
```plain
|
||||
kubectl -n kube-system create serviceaccount tiller
|
||||
|
||||
kubectl create clusterrolebinding tiller \
|
||||
--clusterrole=cluster-admin \
|
||||
--serviceaccount=kube-system:tiller
|
||||
|
||||
helm init --service-account tiller
|
||||
|
||||
# Users in China: You will need to specify a specific tiller-image in order to initialize tiller.
|
||||
# The list of tiller image tags are available here: https://dev.aliyun.com/detail.html?spm=5176.1972343.2.18.ErFNgC&repoId=62085.
|
||||
# When initializing tiller, you'll need to pass in --tiller-image
|
||||
|
||||
helm init --service-account tiller \
|
||||
--tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:<tag>
|
||||
```
|
||||
|
||||
> **Note:** This`tiller`install has full cluster access, which should be acceptable if the cluster is dedicated to Rancher server. See the [Helm docs](https://docs.helm.sh/using_helm/#role-based-access-control) for instructions on restricting `tiller` access to suit your security requirements.
|
||||
|
||||
### Test your Tiller installation
|
||||
|
||||
Run the following command to verify the installation of `tiller` on your cluster:
|
||||
|
||||
```
|
||||
kubectl -n kube-system rollout status deploy/tiller-deploy
|
||||
Waiting for deployment "tiller-deploy" rollout to finish: 0 of 1 updated replicas are available...
|
||||
deployment "tiller-deploy" successfully rolled out
|
||||
```
|
||||
|
||||
And run the following command to validate Helm can talk to the `tiller` service:
|
||||
|
||||
```
|
||||
helm version
|
||||
Client: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}
|
||||
Server: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}
|
||||
```
|
||||
|
||||
### Issues or errors?
|
||||
|
||||
See the [Troubleshooting](troubleshooting.md) page.
|
||||
|
||||
### [Next: Install Rancher](../helm-rancher/helm-rancher.md)
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
### Helm commands show forbidden
|
||||
|
||||
When Helm is initiated in the cluster without specifying the correct `ServiceAccount`, the command `helm init` will succeed but you won't be able to execute most of the other `helm` commands. The following error will be shown:
|
||||
|
||||
```
|
||||
Error: configmaps is forbidden: User "system:serviceaccount:kube-system:default" cannot list configmaps in the namespace "kube-system"
|
||||
```
|
||||
|
||||
To resolve this, the server component (`tiller`) needs to be removed and added with the correct `ServiceAccount`. You can use `helm reset --force` to remove the `tiller` from the cluster. Please check if it is removed using `helm version --server`.
|
||||
|
||||
```
|
||||
helm reset --force
|
||||
Tiller (the Helm server-side component) has been uninstalled from your Kubernetes Cluster.
|
||||
helm version --server
|
||||
Error: could not find tiller
|
||||
```
|
||||
|
||||
When you have confirmed that `tiller` has been removed, please follow the steps provided in [Initialize Helm (Install tiller)](helm-init.md) to install `tiller` with the correct `ServiceAccount`.
|
||||
-244
@@ -1,244 +0,0 @@
|
||||
---
|
||||
title: Chart Options
|
||||
---
|
||||
|
||||
### Common Options
|
||||
|
||||
| Option | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `hostname` | " " | `string` - the Fully Qualified Domain Name for your Rancher Server |
|
||||
| `ingress.tls.source` | "rancher" | `string` - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret" |
|
||||
| `letsEncrypt.email` | " " | `string` - Your email address |
|
||||
| `letsEncrypt.environment` | "production" | `string` - Valid options: "staging, production" |
|
||||
| `privateCA` | false | `bool` - Set to true if your cert is signed by a private CA |
|
||||
|
||||
<br/>
|
||||
|
||||
### Advanced Options
|
||||
|
||||
| Option | Default Value | Description |
|
||||
| --- | --- | --- |
|
||||
| `additionalTrustedCAs` | false | `bool` - See [Additional Trusted CAs](#additional-trusted-cas) |
|
||||
| `addLocal` | "auto" | `string` - Have Rancher detect and import the local Rancher server cluster |
|
||||
| `antiAffinity` | "preferred" | `string` - AntiAffinity rule for Rancher pods - "preferred, required" |
|
||||
| `auditLog.destination` | "sidecar" | `string` - Stream to sidecar container console or hostPath volume - "sidecar, hostPath" |
|
||||
| `auditLog.hostPath` | "/var/log/rancher/audit" | `string` - log file destination on host (only applies when `auditLog.destination` is set to `hostPath`) |
|
||||
| `auditLog.level` | 0 | `int` - set the [API Audit Log](../../../advanced-use-cases/enable-api-audit-log.md) level. 0 is off. [0-3] |
|
||||
| `auditLog.maxAge` | 1 | `int` - maximum number of days to retain old audit log files (only applies when `auditLog.destination` is set to `hostPath`) |
|
||||
| `auditLog.maxBackups` | 1 | `int` - maximum number of audit log files to retain (only applies when `auditLog.destination` is set to `hostPath`) |
|
||||
| `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated (only applies when `auditLog.destination` is set to `hostPath`) |
|
||||
| `busyboxImage` | "busybox" | `string` - Image location for busybox image used to collect audit logs _Note: Available as of v2.2.0_ |
|
||||
| `debug` | false | `bool` - set debug flag on rancher server |
|
||||
| `extraEnv` | [] | `list` - set additional environment variables for Rancher _Note: Available as of v2.2.0_ |
|
||||
| `imagePullSecrets` | [] | `list` - list of names of Secret resource containing private registry credentials |
|
||||
| `ingress.extraAnnotations` | {} | `map` - additional annotations to customize the ingress |
|
||||
| `ingress.configurationSnippet` | "" | `string` - additional Nginx configuration. Can be used for proxy configuration. _Note: Available as of v2.0.15, v2.1.10 and v2.2.4_ |
|
||||
| `proxy` | "" | `string` - HTTP[S] proxy server for Rancher |
|
||||
| `noProxy` | "127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16" | `string` - comma separated list of hostnames or ip address not to use the proxy |
|
||||
| `resources` | {} | `map` - rancher pod resource requests & limits |
|
||||
| `rancherImage` | "rancher/rancher" | `string` - rancher image source |
|
||||
| `rancherImageTag` | same as chart version | `string` - rancher/rancher image tag |
|
||||
| `tls` | "ingress" | `string` - See [External TLS Termination](#external-tls-termination) for details. - "ingress, external" |
|
||||
| `systemDefaultRegistry` | "" | `string` - private registry to be used for all system Docker images, e.g., http://registry.example.com/ _Available as of v2.3.0_ |
|
||||
| `useBundledSystemChart` | `false` | `bool` - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations. _Available as of v2.3.0_
|
||||
|
||||
<br/>
|
||||
|
||||
### API Audit Log
|
||||
|
||||
Enabling the [API Audit Log](../../enable-api-audit-log.md).
|
||||
|
||||
You can collect this log as you would any container log. Enable the [Logging service under Rancher Tools](../../../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md) for the `System` Project on the Rancher server cluster.
|
||||
|
||||
```plain
|
||||
--set auditLog.level=1
|
||||
```
|
||||
|
||||
By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (`rancher-audit-log`) will stream the log to `stdout`. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the `hostPath`, `maxAge`, `maxBackups`, and `maxSize` options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable the [Logging service under Rancher Tools](../../../../../../explanations/integrations-in-rancher/cluster-logging/cluster-logging.md/) for the Rancher server cluster or System Project.
|
||||
|
||||
Set the `auditLog.destination` to `hostPath` to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to `hostPath` you may want to adjust the other auditLog parameters for log rotation.
|
||||
|
||||
### Setting Extra Environment Variables
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
You can set extra environment variables for Rancher server using `extraEnv`. This list uses the same `name` and `value` keys as the container manifest definitions. Remember to quote the values.
|
||||
|
||||
```plain
|
||||
--set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
|
||||
--set 'extraEnv[0].value=1.0'
|
||||
```
|
||||
|
||||
### TLS settings
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
To set a different TLS configuration, you can use the `CATTLE_TLS_MIN_VERSION` and `CATTLE_TLS_CIPHERS` environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:
|
||||
|
||||
```plain
|
||||
--set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
|
||||
--set 'extraEnv[0].value=1.0'
|
||||
```
|
||||
|
||||
See [TLS settings](../../../../../../reference-guides/installation-references/tls-settings.md) for more information and options.
|
||||
|
||||
### Import `local` Cluster
|
||||
|
||||
By default Rancher server will detect and import the `local` cluster it's running on. User with access to the `local` cluster will essentially have "root" access to all the clusters managed by Rancher server.
|
||||
|
||||
If this is a concern in your environment you can set this option to "false" on your initial install.
|
||||
|
||||
> Note: This option is only effective on the initial Rancher install. See [Issue 16522](https://github.com/rancher/rancher/issues/16522) for more information.
|
||||
|
||||
```plain
|
||||
--set addLocal="false"
|
||||
```
|
||||
|
||||
### Customizing your Ingress
|
||||
|
||||
To customize or use a different ingress with Rancher server you can set your own Ingress annotations.
|
||||
|
||||
Example on setting a custom certificate issuer:
|
||||
|
||||
```plain
|
||||
--set ingress.extraAnnotations.'certmanager\.k8s\.io/cluster-issuer'=ca-key-pair
|
||||
```
|
||||
|
||||
_Available as of v2.0.15, v2.1.10 and v2.2.4_
|
||||
|
||||
Example on setting a static proxy header with `ingress.configurationSnippet`. This value is parsed like a template so variables can be used.
|
||||
|
||||
```plain
|
||||
--set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};'
|
||||
```
|
||||
|
||||
### HTTP Proxy
|
||||
|
||||
Rancher requires internet access for some functionality, such as Helm charts. Use `proxy` to set your proxy server.
|
||||
|
||||
Add your IP exceptions to the `noProxy` list. Make sure you add the Service cluster IP range (default: 10.43.0.1/16) and any worker cluster `controlplane` nodes. Rancher supports CIDR notation ranges in this list.
|
||||
|
||||
```plain
|
||||
--set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
|
||||
--set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16"
|
||||
```
|
||||
|
||||
### Additional Trusted CAs
|
||||
|
||||
If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add more trusted CAs to Rancher.
|
||||
|
||||
```plain
|
||||
--set additionalTrustedCAs=true
|
||||
```
|
||||
|
||||
Once the Rancher deployment is created, copy your CA certs in pem format into a file named `ca-additional.pem` and use `kubectl` to create the `tls-ca-additional` secret in the `cattle-system` namespace.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem
|
||||
```
|
||||
|
||||
### Private Registry and Air Gap Installs
|
||||
|
||||
For details on installing Rancher with a private registry, see:
|
||||
|
||||
- [Air Gap: Docker Install](../../../../../../reference-guides/installation-references/tls-settings.md)
|
||||
- [Air Gap: Kubernetes Install](../../air-gap-helm2/air-gap-helm2.md)
|
||||
|
||||
|
||||
### External TLS Termination
|
||||
|
||||
We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.
|
||||
|
||||
You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the `--set tls=external` option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.
|
||||
|
||||
> **Note:** If you are using a Private CA signed certificate, add `--set privateCA=true` and see [Adding TLS Secrets - Using a Private CA Signed Certificate](./tls-secrets.md) to add the CA cert for Rancher.
|
||||
|
||||
Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.
|
||||
|
||||
#### Configuring Ingress for External TLS when Using NGINX v0.25
|
||||
|
||||
In NGINX v0.25, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0220) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the `cluster.yml` to enable the `use-forwarded-headers` option for ingress:
|
||||
|
||||
```yaml
|
||||
ingress:
|
||||
provider: nginx
|
||||
options:
|
||||
use-forwarded-headers: "true"
|
||||
```
|
||||
|
||||
#### Required Headers
|
||||
|
||||
* `Host`
|
||||
* `X-Forwarded-Proto`
|
||||
* `X-Forwarded-Port`
|
||||
* `X-Forwarded-For`
|
||||
|
||||
#### Recommended Timeouts
|
||||
|
||||
* Read Timeout: `1800 seconds`
|
||||
* Write Timeout: `1800 seconds`
|
||||
* Connect Timeout: `30 seconds`
|
||||
|
||||
#### Health Checks
|
||||
|
||||
Rancher will respond `200` to health checks on the `/healthz` endpoint.
|
||||
|
||||
|
||||
#### Example NGINX config
|
||||
|
||||
This NGINX configuration is tested on NGINX 1.14.
|
||||
|
||||
>**Note:** This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/).
|
||||
|
||||
* Replace `IP_NODE1`, `IP_NODE2` and `IP_NODE3` with the IP addresses of the nodes in your cluster.
|
||||
* Replace both occurrences of `FQDN` to the DNS name for Rancher.
|
||||
* Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively.
|
||||
|
||||
```
|
||||
worker_processes 4;
|
||||
worker_rlimit_nofile 40000;
|
||||
|
||||
events {
|
||||
worker_connections 8192;
|
||||
}
|
||||
|
||||
http {
|
||||
upstream rancher {
|
||||
server IP_NODE_1:80;
|
||||
server IP_NODE_2:80;
|
||||
server IP_NODE_3:80;
|
||||
}
|
||||
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default Upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name FQDN;
|
||||
ssl_certificate /certs/fullchain.pem;
|
||||
ssl_certificate_key /certs/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_pass http://rancher;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
# This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
|
||||
proxy_read_timeout 900s;
|
||||
proxy_buffering off;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name FQDN;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
}
|
||||
```
|
||||
-231
@@ -1,231 +0,0 @@
|
||||
---
|
||||
title: "4. Install Rancher"
|
||||
---
|
||||
|
||||
Rancher installation is managed using the Helm package manager for Kubernetes. Use `helm` to install the prerequisite and charts to install Rancher.
|
||||
|
||||
For systems without direct internet access, see [Air Gap: Kubernetes install](../../air-gap-helm2/install-rancher.md).
|
||||
|
||||
Refer to the [Helm version requirements](../../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
|
||||
|
||||
### Add the Helm Chart Repository
|
||||
|
||||
Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Version of Rancher](../../../../resources/choose-a-rancher-version.md).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
### Choose your SSL Configuration
|
||||
|
||||
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
There are three recommended options for the source of the certificate.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](chart-options.md#external-tls-termination).
|
||||
|
||||
| Configuration | Chart option | Description | Requires cert-manager |
|
||||
|-----|-----|-----|-----|
|
||||
| [Rancher Generated Certificates](#rancher-generated-certificates) | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/>This is the **default** | [yes](#optional-install-cert-manager) |
|
||||
| [Let’s Encrypt](#let-s-encrypt) | `ingress.tls.source=letsEncrypt` | Use [Let's Encrypt](https://letsencrypt.org/) to issue a certificate | [yes](#optional-install-cert-manager) |
|
||||
| [Certificates from Files](#certificates-from-files) | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s) | no |
|
||||
|
||||
### Optional: Install cert-manager
|
||||
|
||||
**Note:** cert-manager is only required for certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) and Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`). You should skip this step if you are using your own certificate files (option `ingress.tls.source=secret`) or if you use [TLS termination on an External Load Balancer](chart-options.md#external-tls-termination).
|
||||
|
||||
> **Important:**
|
||||
> Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.
|
||||
|
||||
> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../../../resources/upgrade-cert-manager.md).
|
||||
|
||||
Rancher relies on [cert-manager](https://github.com/jetstack/cert-manager) to issue certificates from Rancher's own generated CA or to request Let's Encrypt certificates.
|
||||
|
||||
These instructions are adapted from the [official cert-manager documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#installing-with-helm).
|
||||
|
||||
|
||||
1. Install the CustomResourceDefinition resources separately
|
||||
```plain
|
||||
kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml
|
||||
```
|
||||
|
||||
1. Create the namespace for cert-manager
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Label the cert-manager namespace to disable resource validation
|
||||
```plain
|
||||
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true
|
||||
```
|
||||
|
||||
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 cert-manager Helm chart
|
||||
```plain
|
||||
helm install \
|
||||
--name cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v0.14.2 \
|
||||
jetstack/cert-manager
|
||||
```
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace cert-manager
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-7cbdc48784-rpgnt 1/1 Running 0 3m
|
||||
cert-manager-webhook-5b5dd6999-kst4x 1/1 Running 0 3m
|
||||
cert-manager-cainjector-3ba5cd2bcd-de332x 1/1 Running 0 3m
|
||||
```
|
||||
|
||||
If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check the [troubleshooting](https://docs.cert-manager.io/en/latest/getting-started/troubleshooting.html) guide.
|
||||
|
||||
<br/>
|
||||
|
||||
#### Rancher Generated Certificates
|
||||
|
||||
> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding.
|
||||
|
||||
The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface. Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command.
|
||||
|
||||
- Set the `hostname` to the DNS name you pointed at your load balancer.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
#### Let's Encrypt
|
||||
|
||||
> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding.
|
||||
|
||||
This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. This configuration uses HTTP validation (`HTTP-01`) so the load balancer must have a public DNS record and be accessible from the internet.
|
||||
|
||||
In the following command,
|
||||
|
||||
- Set `hostname` to the public DNS record that resolves to your load balancer.
|
||||
- Set `ingress.tls.source` to `letsEncrypt`.
|
||||
- Set `letsEncrypt.email` to the email address used for communication about your certificate (for example, expiry notices).
|
||||
- Set `letsEncrypt.ingress.class` to whatever your ingress controller is, e.g., `traefik`, `nginx`, `haproxy`, etc.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=letsEncrypt \
|
||||
--set letsEncrypt.email=me@example.org \
|
||||
--set letsEncrypt.ingress.class=nginx
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
#### Certificates from Files
|
||||
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use.
|
||||
|
||||
|
||||
> **Note:** The `Common Name` or a `Subject Alternative Names` entry in the server certificate must match the `hostname` option, or the ingress controller will fail to configure correctly. Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers/applications. If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?](../../../../../../faq/technical-items.md#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate)
|
||||
|
||||
- Set `hostname` and set `ingress.tls.source` to `secret`.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
```
|
||||
|
||||
If you are using a Private CA signed certificate , add `--set privateCA=true` to the command:
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
--set privateCA=true
|
||||
```
|
||||
|
||||
Now that Rancher is deployed, see [Adding TLS Secrets](tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
After adding the secrets, check if Rancher was rolled out successfully:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get deploy rancher
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
rancher 3 3 3 3 3m
|
||||
```
|
||||
|
||||
It should show the same count for `DESIRED` and `AVAILABLE`.
|
||||
|
||||
### Advanced Configurations
|
||||
|
||||
The Rancher chart configuration has many options for customizing the install to suit your specific environment. Here are some common advanced scenarios.
|
||||
|
||||
* [HTTP Proxy](../../../../../../reference-guides/installation-references/helm-chart-options.md)
|
||||
* [Private Docker Image Registry](../../../../../../reference-guides/installation-references/helm-chart-options.md#private-registry-and-air-gap-installs)
|
||||
* [TLS Termination on an External Load Balancer](chart-options.md#external-tls-termination)
|
||||
|
||||
See the [Chart Options](chart-options.md) for the full list of options.
|
||||
|
||||
### Save your options
|
||||
|
||||
Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.
|
||||
|
||||
### Finishing Up
|
||||
|
||||
That's it you should have a functional Rancher server. Point a browser at the hostname you picked and you should be greeted by the colorful login page.
|
||||
|
||||
Doesn't work? Take a look at the [Troubleshooting](troubleshooting.md) Page
|
||||
-31
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Adding Kubernetes TLS Secrets
|
||||
description: Read about how to populate the Kubernetes TLS secret for a Rancher installation
|
||||
---
|
||||
|
||||
Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key.
|
||||
|
||||
Combine the server certificate followed by any intermediate certificate(s) needed into a file named `tls.crt`. Copy your certificate key into a file named `tls.key`.
|
||||
|
||||
Use `kubectl` with the `tls` secret type to create the secrets.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system create secret tls tls-rancher-ingress \
|
||||
--cert=tls.crt \
|
||||
--key=tls.key
|
||||
```
|
||||
|
||||
> **Note:** If you want to replace the certificate, you can delete the `tls-rancher-ingress` secret using `kubectl -n cattle-system delete secret tls-rancher-ingress` and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.
|
||||
|
||||
### Using a Private CA Signed Certificate
|
||||
|
||||
If you are using a private CA, Rancher requires a copy of the private CA's root certificate or certificate chain, which the Rancher Agent uses to validate the connection to the server.
|
||||
|
||||
Create a file named `cacerts.pem` that only contains the root CA certificate or certificate chain from your private CA, and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace.
|
||||
|
||||
>**Important:** Make sure the file is called `cacerts.pem` as Rancher uses that filename to configure the CA certificate.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system create secret generic tls-ca \
|
||||
--from-file=cacerts.pem
|
||||
```
|
||||
-132
@@ -1,132 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
### Where is everything
|
||||
|
||||
Most of the troubleshooting will be done on objects in these 3 namespaces.
|
||||
|
||||
* `cattle-system` - `rancher` deployment and pods.
|
||||
* `ingress-nginx` - Ingress controller pods and services.
|
||||
* `kube-system` - `tiller` and `cert-manager` pods.
|
||||
|
||||
### "default backend - 404"
|
||||
|
||||
A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration.
|
||||
|
||||
Things to check
|
||||
|
||||
* [Is Rancher Running](#is-rancher-running)
|
||||
* [Cert CN is "Kubernetes Ingress Controller Fake Certificate"](#cert-cn-is-kubernetes-ingress-controller-fake-certificate)
|
||||
|
||||
### Is Rancher Running
|
||||
|
||||
Use `kubectl` to check the `cattle-system` system namespace and see if the Rancher pods are in a Running state.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get pods
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m
|
||||
```
|
||||
|
||||
If the state is not `Running`, run a `describe` on the pod and check the Events.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system describe pod
|
||||
|
||||
...
|
||||
Events:
|
||||
Type Reason Age From Message
|
||||
---- ------ ---- ---- -------
|
||||
Normal Scheduled 11m default-scheduler Successfully assigned rancher-784d94f59b-vgqzh to localhost
|
||||
Normal SuccessfulMountVolume 11m kubelet, localhost MountVolume.SetUp succeeded for volume "rancher-token-dj4mt"
|
||||
Normal Pulling 11m kubelet, localhost pulling image "rancher/rancher:v2.0.4"
|
||||
Normal Pulled 11m kubelet, localhost Successfully pulled image "rancher/rancher:v2.0.4"
|
||||
Normal Created 11m kubelet, localhost Created container
|
||||
Normal Started 11m kubelet, localhost Started container
|
||||
```
|
||||
|
||||
### Checking the rancher logs
|
||||
|
||||
Use `kubectl` to list the pods.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get pods
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
pod/rancher-784d94f59b-vgqzh 1/1 Running 0 10m
|
||||
```
|
||||
|
||||
Use `kubectl` and the pod name to list the logs from the pod.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh
|
||||
```
|
||||
|
||||
### Cert CN is "Kubernetes Ingress Controller Fake Certificate"
|
||||
|
||||
Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert.
|
||||
|
||||
> **Note:** if you are using LetsEncrypt to issue certs it can sometimes take a few minuets to issue the cert.
|
||||
|
||||
#### cert-manager issued certs (Rancher Generated or LetsEncrypt)
|
||||
|
||||
`cert-manager` has 3 parts.
|
||||
|
||||
* `cert-manager` pod in the `kube-system` namespace.
|
||||
* `Issuer` object in the `cattle-system` namespace.
|
||||
* `Certificate` object in the `cattle-system` namespace.
|
||||
|
||||
Work backwards and do a `kubectl describe` on each object and check the events. You can track down what might be missing.
|
||||
|
||||
For example there is a problem with the Issuer:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system describe certificate
|
||||
...
|
||||
Events:
|
||||
Type Reason Age From Message
|
||||
---- ------ ---- ---- -------
|
||||
Warning IssuerNotReady 18s (x23 over 19m) cert-manager Issuer rancher not ready
|
||||
```
|
||||
|
||||
```
|
||||
kubectl -n cattle-system describe issuer
|
||||
...
|
||||
Events:
|
||||
Type Reason Age From Message
|
||||
---- ------ ---- ---- -------
|
||||
Warning ErrInitIssuer 19m (x12 over 19m) cert-manager Error initializing issuer: secret "tls-rancher" not found
|
||||
Warning ErrGetKeyPair 9m (x16 over 19m) cert-manager Error getting keypair for CA issuer: secret "tls-rancher" not found
|
||||
```
|
||||
|
||||
#### Bring Your Own SSL Certs
|
||||
|
||||
Your certs get applied directly to the Ingress object in the `cattle-system` namespace.
|
||||
|
||||
Check the status of the Ingress object and see if its ready.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system describe ingress
|
||||
```
|
||||
|
||||
If its ready and the SSL is still not working you may have a malformed cert or secret.
|
||||
|
||||
Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.
|
||||
|
||||
```
|
||||
kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller
|
||||
...
|
||||
W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found
|
||||
```
|
||||
|
||||
### no matches for kind "Issuer"
|
||||
|
||||
The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown:
|
||||
|
||||
```
|
||||
Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1"
|
||||
```
|
||||
|
||||
Install cert-manager and try installing Rancher again.
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Installation Using Helm 2
|
||||
---
|
||||
|
||||
> After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.
|
||||
>
|
||||
> If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> This section provides a copy of the older high-availability Kubernetes Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
For production environments, we recommend installing Rancher in a high-availability configuration so that your user base can always access Rancher Server. When installed in a Kubernetes cluster, Rancher will integrate with the cluster's etcd database and take advantage of Kubernetes scheduling for high-availability.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster with Rancher Kubernetes Engine (RKE) and installing the Rancher chart with the Helm package manager.
|
||||
|
||||
> **Important:** The Rancher management server can only be run on an RKE-managed Kubernetes cluster. Use of Rancher on hosted Kubernetes or other providers is not supported.
|
||||
|
||||
> **Important:** For the best performance, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
- DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
|
||||
- The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
|
||||
- The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
|
||||
- The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
|
||||
|
||||
<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>
|
||||
|
||||
## Required Tools
|
||||
|
||||
The following CLI tools are required for this install. Please make sure these tools are installed and available in your `$PATH`
|
||||
|
||||
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
|
||||
- [rke](https://rancher.com/docs/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters.
|
||||
- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](../../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
- [Create Nodes and Load Balancer](create-nodes-lb/create-nodes-lb.md)
|
||||
- [Install Kubernetes with RKE](kubernetes-rke/kubernetes-rke.md)
|
||||
- [Initialize Helm (tiller)](helm-init/helm-init.md)
|
||||
- [Install Rancher](helm-rancher/helm-rancher.md)
|
||||
|
||||
## Additional Install Options
|
||||
|
||||
- [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md)
|
||||
|
||||
## Previous Methods
|
||||
|
||||
[RKE add-on install](rke-add-on/rke-add-on.md)
|
||||
|
||||
> **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
> Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
> If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
-131
@@ -1,131 +0,0 @@
|
||||
---
|
||||
title: "2. Install Kubernetes with RKE"
|
||||
---
|
||||
|
||||
Use RKE to install Kubernetes with a high availability etcd configuration.
|
||||
|
||||
>**Note:** For systems without direct internet access see [Air Gap: Kubernetes install](../../air-gap-helm2/air-gap-helm2.md) for install details.
|
||||
|
||||
### Create the `rancher-cluster.yml` File
|
||||
|
||||
Using the sample below create the `rancher-cluster.yml` file. Replace the IP Addresses in the `nodes` list with the IP address or DNS names of the 3 nodes you created.
|
||||
|
||||
> **Note:** If your node has public and internal addresses, it is recommended to set the `internal_address:` so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the `internal_address:` if you want to use self-referencing security groups or firewalls.
|
||||
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
#### Common RKE Nodes Options
|
||||
|
||||
| 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](https://rancher.com/docs/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](../../tune-etcd-for-large-installs.md).
|
||||
|
||||
### Run RKE
|
||||
|
||||
```
|
||||
rke up --config ./rancher-cluster.yml
|
||||
```
|
||||
|
||||
When finished, it should end with the line: `Finished building Kubernetes cluster successfully`.
|
||||
|
||||
### Testing Your Cluster
|
||||
|
||||
RKE should have created a file `kube_config_rancher-cluster.yml`. This file has the credentials for `kubectl` and `helm`.
|
||||
|
||||
> **Note:** If you have used a different file name from `rancher-cluster.yml`, then the kube config file will be named `kube_config_<FILE_NAME>.yml`.
|
||||
|
||||
You can copy this file to `$HOME/.kube/config` or if you are working with multiple Kubernetes clusters, set the `KUBECONFIG` environmental variable to the path of `kube_config_rancher-cluster.yml`.
|
||||
|
||||
```
|
||||
export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml
|
||||
```
|
||||
|
||||
Test your connectivity with `kubectl` and see if all your nodes are in `Ready` state.
|
||||
|
||||
```
|
||||
kubectl get nodes
|
||||
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
165.227.114.63 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
165.227.116.167 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
165.227.127.226 Ready controlplane,etcd,worker 11m v1.13.5
|
||||
```
|
||||
|
||||
### Check the Health of Your Cluster Pods
|
||||
|
||||
Check that all the required pods and containers are healthy are ready to continue.
|
||||
|
||||
* Pods are in `Running` or `Completed` state.
|
||||
* `READY` column shows all the containers are running (i.e. `3/3`) for pods with `STATUS` `Running`
|
||||
* Pods with `STATUS` `Completed` are run-once Jobs. For these pods `READY` should be `0/1`.
|
||||
|
||||
```
|
||||
kubectl get pods --all-namespaces
|
||||
|
||||
NAMESPACE NAME READY STATUS RESTARTS AGE
|
||||
ingress-nginx nginx-ingress-controller-tnsn4 1/1 Running 0 30s
|
||||
ingress-nginx nginx-ingress-controller-tw2ht 1/1 Running 0 30s
|
||||
ingress-nginx nginx-ingress-controller-v874b 1/1 Running 0 30s
|
||||
kube-system canal-jp4hz 3/3 Running 0 30s
|
||||
kube-system canal-z2hg8 3/3 Running 0 30s
|
||||
kube-system canal-z6kpw 3/3 Running 0 30s
|
||||
kube-system kube-dns-7588d5b5f5-sf4vh 3/3 Running 0 30s
|
||||
kube-system kube-dns-autoscaler-5db9bbb766-jz2k6 1/1 Running 0 30s
|
||||
kube-system metrics-server-97bc649d5-4rl2q 1/1 Running 0 30s
|
||||
kube-system rke-ingress-controller-deploy-job-bhzgm 0/1 Completed 0 30s
|
||||
kube-system rke-kubedns-addon-deploy-job-gl7t4 0/1 Completed 0 30s
|
||||
kube-system rke-metrics-addon-deploy-job-7ljkc 0/1 Completed 0 30s
|
||||
kube-system rke-network-plugin-deploy-job-6pbgj 0/1 Completed 0 30s
|
||||
```
|
||||
|
||||
### Save Your Files
|
||||
|
||||
> **Important**
|
||||
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
|
||||
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_rancher-cluster.yml`: The [Kubeconfig file](https://rancher.com/docs/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](https://rancher.com/docs/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](troubleshooting.md) page.
|
||||
|
||||
### [Next: Initialize Helm (Install tiller)](../helm-init/helm-init.md)
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
### canal Pods show READY 2/3
|
||||
|
||||
The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups.
|
||||
|
||||
Once the network issue is resolved, the `canal` pods should timeout and restart to establish their connections.
|
||||
|
||||
### nginx-ingress-controller Pods show RESTARTS
|
||||
|
||||
The most common cause of this issue is the `canal` pods have failed to establish the overlay network. See [canal Pods show READY `2/3`](#canal-pods-show-ready-23) for troubleshooting.
|
||||
|
||||
### Failed to set up SSH tunneling for host [xxx.xxx.xxx.xxx]: Can't retrieve Docker Info
|
||||
|
||||
#### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)
|
||||
|
||||
* User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command `docker ps`:
|
||||
|
||||
```
|
||||
$ ssh user@server
|
||||
user@server$ docker ps
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
```
|
||||
|
||||
See [Manage Docker as a non-root user](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`.
|
||||
-52
@@ -1,52 +0,0 @@
|
||||
---
|
||||
title: Enable API Auditing
|
||||
---
|
||||
|
||||
>**Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../resources/choose-a-rancher-version.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
If you're using RKE to install Rancher, you can use directives to enable API Auditing for your Rancher install. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use.
|
||||
|
||||
## In-line Arguments
|
||||
|
||||
Enable API Auditing using RKE by adding arguments to your Rancher container.
|
||||
|
||||
To enable API auditing:
|
||||
|
||||
- Add API Auditing arguments (`args`) to your Rancher container.
|
||||
- Declare a `mountPath` in the `volumeMounts` directive of the container.
|
||||
- Declare a `path` in the `volumes` directive.
|
||||
|
||||
For more information about each argument, its syntax, and how to view API Audit logs, see [Rancher v2.0 Documentation: API Auditing](../../enable-api-audit-log.md).
|
||||
|
||||
```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
|
||||
```
|
||||
-380
@@ -1,380 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (TCP/Layer 4)
|
||||
---
|
||||
import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a High-availability Kubernetes install with an RKE add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:
|
||||
|
||||
- Layer 4 load balancer (TCP)
|
||||
- [NGINX ingress controller with SSL termination (HTTPS)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In a Kubernetes setup that uses a layer 4 load balancer, the load balancer accepts Rancher client connections over the TCP/UDP protocols (i.e., the transport level). The load balancer then forwards these connections to individual cluster nodes without reading the request itself. Because the load balancer cannot read the packets it's forwarding, the routing decisions it can make are limited.
|
||||
|
||||
<sup>Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers</sup>
|
||||
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
We will be using NGINX as our Layer 4 Load Balancer (TCP). NGINX will forward all connections to one of your Rancher nodes. If you want to use Amazon NLB, you can skip this step and use [Amazon NLB configuration](nlb.md)
|
||||
|
||||
>**Note:**
|
||||
> In this configuration, the load balancer is positioned in front of your Linux hosts. The load balancer can be any host that you have available that's capable of running NGINX.
|
||||
>
|
||||
>One caveat: do not use one of your Rancher nodes as the load balancer.
|
||||
|
||||
### A. Install NGINX
|
||||
|
||||
Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems. For help installing NGINX, refer to their [install documentation](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 how to install and enable the NGINX `stream` module on your operating system.
|
||||
|
||||
### B. Create NGINX Configuration
|
||||
|
||||
After installing NGINX, you need to update the NGINX config 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 `IP_NODE_1`, `IP_NODE_2`, and `IP_NODE_3` with the IPs of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
>**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/).
|
||||
|
||||
**Example NGINX config:**
|
||||
```
|
||||
worker_processes 4;
|
||||
worker_rlimit_nofile 40000;
|
||||
|
||||
events {
|
||||
worker_connections 8192;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
stream {
|
||||
upstream rancher_servers {
|
||||
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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE Config File Template
|
||||
|
||||
RKE uses a `.yml` config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.
|
||||
|
||||
1. Download one of following templates, depending on the SSL certificate you're using.
|
||||
|
||||
- [Template for self-signed certificate<br/> `3-node-certificate.yml`](../../../cluster-yml-templates/node-certificate.md)
|
||||
- [Template for certificate signed by recognized CA<br/> `3-node-certificate-recognizedca.yml`](../../../cluster-yml-templates/node-certificate-recognizedca.md)
|
||||
|
||||
>**Advanced Config Options:**
|
||||
>
|
||||
>- Want records of all transactions with the Rancher API? Enable the [API Auditing](../../../enable-api-audit-log.md) feature by editing your RKE config file. For more information, see how to enable it in [your RKE config file](../api-auditing.md).
|
||||
>- Want to know the other config options available for your RKE template? See the [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
> When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) >for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in [base64](#base64).
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.
|
||||
|
||||
1. In `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
2. In `kind: Secret` with `name: cattle-keys-server`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`).
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
|
||||
**Step Result:** The file should look like the example below (the base64 encoded string should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the intermediate certificates in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included.
|
||||
|
||||
In the `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There are two references to `<FQDN>` in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
In the `kind: Ingress` with `name: cattle-ingress-http`:
|
||||
|
||||
* Replace `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
After replacing `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns), the file should look like the example below (`rancher.yourdomain.com` is the FQDN used in this example):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: rancher.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
tls:
|
||||
- secretName: cattle-keys-ingress
|
||||
hosts:
|
||||
- rancher.yourdomain.com
|
||||
```
|
||||
|
||||
Save the `.yml` file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](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.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** The output should be similar to the snippet below:
|
||||
|
||||
```
|
||||
INFO[0000] Building Kubernetes cluster
|
||||
INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
|
||||
INFO[0000] [network] Deploying port listener containers
|
||||
INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
|
||||
...
|
||||
INFO[0101] Finished building Kubernetes cluster successfully
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [High Availability Back Up and Restore](../../../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/backup-restore-and-disaster-recovery.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
-178
@@ -1,178 +0,0 @@
|
||||
---
|
||||
title: Amazon NLB Configuration
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a High-availability Kubernetes install with an RKE add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
## Objectives
|
||||
|
||||
Configuring an Amazon NLB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
|
||||
|
||||
1. [Create Target Groups](#create-target-groups)
|
||||
|
||||
Begin by creating two target groups for the **TCP** protocol, one regarding TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups.
|
||||
|
||||
2. [Register Targets](#register-targets)
|
||||
|
||||
Add your Linux nodes to the target groups.
|
||||
|
||||
3. [Create Your NLB](#create-your-nlb)
|
||||
|
||||
Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in **1. Create Target Groups**.
|
||||
|
||||
|
||||
## Create Target Groups
|
||||
|
||||
Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but its convenient to add a listener for port 80 which will be redirected to port 443 automatically. The NGINX controller on the nodes will make sure that port 80 gets redirected to port 443.
|
||||
|
||||
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.
|
||||
|
||||
The Target Groups configuration resides in the **Load Balancing** section of the **EC2** service. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**.
|
||||
|
||||
|
||||
|
||||
Click **Create target group** to create the first target group, regarding TCP port 443.
|
||||
|
||||
### Target Group (TCP port 443)
|
||||
|
||||
Configure the first target group according to the table below. Screenshots of the configuration are shown just below the table.
|
||||
|
||||
Option | Setting
|
||||
--------------------------------------|------------------------------------
|
||||
Target Group Name | `rancher-tcp-443`
|
||||
Protocol | `TCP`
|
||||
Port | `443`
|
||||
Target type | `instance`
|
||||
VPC | Choose your VPC
|
||||
Protocol<br/>(Health Check) | `HTTP`
|
||||
Path<br/>(Health Check) | `/healthz`
|
||||
Port (Advanced health check) | `override`,`80`
|
||||
Healthy threshold (Advanced health) | `3`
|
||||
Unhealthy threshold (Advanced) | `3`
|
||||
Timeout (Advanced) | `6 seconds`
|
||||
Interval (Advanced) | `10 second`
|
||||
Success codes | `200-399`
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 443 settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 443 Advanced settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
|
||||
Click **Create target group** to create the second target group, regarding TCP port 80.
|
||||
|
||||
### Target Group (TCP port 80)
|
||||
|
||||
Configure the second target group according to the table below. Screenshots of the configuration are shown just below the table.
|
||||
|
||||
Option | Setting
|
||||
--------------------------------------|------------------------------------
|
||||
Target Group Name | `rancher-tcp-80`
|
||||
Protocol | `TCP`
|
||||
Port | `80`
|
||||
Target type | `instance`
|
||||
VPC | Choose your VPC
|
||||
Protocol<br/>(Health Check) | `HTTP`
|
||||
Path<br/>(Health Check) | `/healthz`
|
||||
Port (Advanced health check) | `traffic port`
|
||||
Healthy threshold (Advanced health) | `3`
|
||||
Unhealthy threshold (Advanced) | `3`
|
||||
Timeout (Advanced) | `6 seconds`
|
||||
Interval (Advanced) | `10 second`
|
||||
Success codes | `200-399`
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 80 settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Target group TCP port 80 Advanced settings**<br/>
|
||||
|
||||
|
||||
***
|
||||
|
||||
## Register Targets
|
||||
|
||||
Next, add your Linux nodes to both target groups.
|
||||
|
||||
Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**.
|
||||
|
||||
|
||||
|
||||
Select the instances (Linux nodes) you want to add, and click **Add to registered**.
|
||||
|
||||
***
|
||||
**Screenshot Add targets to target group TCP port 443**<br/>
|
||||
|
||||
|
||||
|
||||
***
|
||||
**Screenshot Added targets to target group TCP port 443**<br/>
|
||||
|
||||
|
||||
|
||||
When the instances are added, click **Save** on the bottom right of the screen.
|
||||
|
||||
Repeat those steps, replacing **rancher-tcp-443** with **rancher-tcp-80**. The same instances need to be added as targets to this target group.
|
||||
|
||||
## Create Your NLB
|
||||
|
||||
Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in [Create Target Groups](#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**.
|
||||
|
||||
5. Complete the **Step 1: Configure Load Balancer** form.
|
||||
- **Basic Configuration**
|
||||
|
||||
- Name: `rancher`
|
||||
- Scheme: `internet-facing`
|
||||
- **Listeners**
|
||||
|
||||
Add the **Load Balancer Protocols** and **Load Balancer Ports** below.
|
||||
- `TCP`: `443`
|
||||
|
||||
- **Availability Zones**
|
||||
|
||||
- Select Your **VPC** and **Availability Zones**.
|
||||
|
||||
6. Complete the **Step 2: Configure Routing** form.
|
||||
|
||||
- From the **Target Group** drop-down, choose **Existing target group**.
|
||||
|
||||
- From the **Name** drop-down, choose `rancher-tcp-443`.
|
||||
|
||||
- Open **Advanced health check settings**, and configure **Interval** to `10 seconds`.
|
||||
|
||||
7. Complete **Step 3: Register Targets**. Since you registered your targets earlier, all you have to do is click **Next: Review**.
|
||||
|
||||
8. Complete **Step 4: Review**. Look over the load balancer details and click **Create** when you're satisfied.
|
||||
|
||||
9. After AWS creates the NLB, click **Close**.
|
||||
|
||||
## Add listener to NLB for TCP port 80
|
||||
|
||||
1. Select your newly created NLB and select the **Listeners** tab.
|
||||
|
||||
2. Click **Add listener**.
|
||||
|
||||
3. Use `TCP`:`80` as **Protocol** : **Port**
|
||||
|
||||
4. Click **Add action** and choose **Forward to...**
|
||||
|
||||
5. From the **Forward to** drop-down, choose `rancher-tcp-80`.
|
||||
|
||||
6. Click **Save** in the top right of the screen.
|
||||
-100
@@ -1,100 +0,0 @@
|
||||
---
|
||||
title: Amazon ALB Configuration
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Kubernetes Rancher. For details, see the [Kubernetes Install ](../../../../../resources/choose-a-rancher-version.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
## Objectives
|
||||
|
||||
Configuring an Amazon ALB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
|
||||
|
||||
1. [Create Target Group](#create-target-group)
|
||||
|
||||
Begin by creating one target group for the http protocol. You'll add your Linux nodes to this group.
|
||||
|
||||
2. [Register Targets](#register-targets)
|
||||
|
||||
Add your Linux nodes to the target group.
|
||||
|
||||
3. [Create Your ALB](#create-your-alb)
|
||||
|
||||
Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target groups you created in **1. Create Target Groups**.
|
||||
|
||||
|
||||
## Create Target Group
|
||||
|
||||
Your first ALB configuration step is to create one target group for HTTP.
|
||||
|
||||
Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started.
|
||||
|
||||
The document below will guide you through this process. Use the data in the tables below to complete the procedure.
|
||||
|
||||
[Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html)
|
||||
|
||||
### Target Group (HTTP)
|
||||
|
||||
Option | Setting
|
||||
----------------------------|------------------------------------
|
||||
Target Group Name | `rancher-http-80`
|
||||
Protocol | `HTTP`
|
||||
Port | `80`
|
||||
Target type | `instance`
|
||||
VPC | Choose your VPC
|
||||
Protocol<br/>(Health Check) | `HTTP`
|
||||
Path<br/>(Health Check) | `/healthz`
|
||||
|
||||
## Register Targets
|
||||
|
||||
Next, add your Linux nodes to your target group.
|
||||
|
||||
[Amazon Documentation: Register Targets with Your Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-register-targets.html)
|
||||
|
||||
### Create Your ALB
|
||||
|
||||
Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target group you created in [Create Target Group](#create-target-group).
|
||||
|
||||
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 **Application Load Balancer**.
|
||||
|
||||
5. Complete the **Step 1: Configure Load Balancer** form.
|
||||
- **Basic Configuration**
|
||||
|
||||
- Name: `rancher-http`
|
||||
- Scheme: `internet-facing`
|
||||
- IP address type: `ipv4`
|
||||
- **Listeners**
|
||||
|
||||
Add the **Load Balancer Protocols** and **Load Balancer Ports** below.
|
||||
- `HTTP`: `80`
|
||||
- `HTTPS`: `443`
|
||||
|
||||
- **Availability Zones**
|
||||
|
||||
- Select Your **VPC** and **Availability Zones**.
|
||||
|
||||
6. Complete the **Step 2: Configure Security Settings** form.
|
||||
|
||||
Configure the certificate you want to use for SSL termination.
|
||||
|
||||
7. Complete the **Step 3: Configure Security Groups** form.
|
||||
|
||||
8. Complete the **Step 4: Configure Routing** form.
|
||||
|
||||
- From the **Target Group** drop-down, choose **Existing target group**.
|
||||
|
||||
- Add target group `rancher-http-80`.
|
||||
|
||||
9. Complete **Step 5: Register Targets**. Since you registered your targets earlier, all you have to do it click **Next: Review**.
|
||||
|
||||
10. Complete **Step 6: Review**. Look over the load balancer details and click **Create** when you're satisfied.
|
||||
|
||||
11. After AWS creates the ALB, click **Close**.
|
||||
-270
@@ -1,270 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (HTTPS/Layer 7)
|
||||
---
|
||||
import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to move to using the Helm chart.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:
|
||||
|
||||
- Layer 7 Loadbalancer with SSL termination (HTTPS)
|
||||
- [NGINX Ingress controller (HTTP)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In an Kubernetes setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.
|
||||
|
||||
<sup>Kubernetes Rancher install with layer 7 load balancer, depicting SSL termination at load balancer</sup>
|
||||
|
||||
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
When using a load balancer in front of Rancher, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto: https`, this redirect is disabled. This is the expected configuration when terminating SSL externally.
|
||||
|
||||
The load balancer has to be configured to support the following:
|
||||
|
||||
* **WebSocket** connections
|
||||
* **SPDY** / **HTTP/2** protocols
|
||||
* Passing / setting the following headers:
|
||||
|
||||
| Header | Value | Description |
|
||||
|---------------------|----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `Host` | FQDN 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.<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. |
|
||||
| `X-Forwarded-For` | IP of the client connection. | To identify the originating IP address of a client. |
|
||||
|
||||
Health checks can be executed on the `/healthz` endpoint of the node, this will return HTTP 200.
|
||||
|
||||
We have example configurations for the following load balancers:
|
||||
|
||||
* [Amazon ALB configuration](alb.md)
|
||||
* [NGINX configuration](nginx.md)
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE Config File Template
|
||||
|
||||
RKE uses a YAML config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.
|
||||
|
||||
1. Download one of following templates, depending on the SSL certificate you're using.
|
||||
|
||||
- [Template for self-signed certificate<br/> `3-node-externalssl-certificate.yml`](../../../cluster-yml-templates/node-externalssl-certificate.md)
|
||||
- [Template for certificate signed by recognized CA<br/> `3-node-externalssl-recognizedca.yml`](../../../cluster-yml-templates/node-externalssl-recognizedca.md)
|
||||
|
||||
>**Advanced Config Options:**
|
||||
>
|
||||
>- Want records of all transactions with the Rancher API? Enable the [API Auditing](../../../enable-api-audit-log.md) feature by editing your RKE config file. For more information, see how to enable it in [your RKE config file](../api-auditing.md).
|
||||
>- Want to know the other config options available for your RKE template? See the [RKE Documentation: Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in base64.
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../../../../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
In `kind: Secret` with `name: cattle-keys-ingress`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`)
|
||||
|
||||
>**Note:** The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part.
|
||||
</details>
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There is one reference to `<FQDN>` in the RKE config file. Replace this reference with the FQDN you chose in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
1. Open `rancher-cluster.yml`.
|
||||
|
||||
2. In the `kind: Ingress` with `name: cattle-ingress-http:`
|
||||
|
||||
Replace `<FQDN>` with the FQDN chosen in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: rancher.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
```
|
||||
|
||||
|
||||
3. Save the file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](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.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** The output should be similar to the snippet below:
|
||||
|
||||
```
|
||||
INFO[0000] Building Kubernetes cluster
|
||||
INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
|
||||
INFO[0000] [network] Deploying port listener containers
|
||||
INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
|
||||
...
|
||||
INFO[0101] Finished building Kubernetes cluster successfully
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the `rancher-cluster.yml` file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Creating Backups—High Availability Back Up and Restore](../../../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) to learn how to backup your Rancher Server in case of a disaster scenario.
|
||||
- Create a Kubernetes cluster: [Creating a Cluster](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
-37
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: NGINX Configuration
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/choose-a-rancher-version.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
## Install NGINX
|
||||
|
||||
Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems.
|
||||
|
||||
For help installing NGINX, refer to their [install documentation](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/).
|
||||
|
||||
## Create NGINX Configuration
|
||||
|
||||
See [Example NGINX config](../../helm-rancher/chart-options.md#example-nginx-config).
|
||||
|
||||
## Run NGINX
|
||||
|
||||
* Reload or restart NGINX
|
||||
|
||||
````
|
||||
# Reload NGINX
|
||||
nginx -s reload
|
||||
|
||||
# Restart NGINX
|
||||
# Depending on your Linux distribution
|
||||
service nginx restart
|
||||
systemctl restart nginx
|
||||
````
|
||||
|
||||
## Browse to Rancher UI
|
||||
|
||||
You should now be to able to browse to `https://FQDN`.
|
||||
-68
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: HTTP Proxy Configuration
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../resources/choose-a-rancher-version.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.
|
||||
|
||||
Make sure `NO_PROXY` contains the network addresses, network address ranges and domains that should be excluded from using the proxy.
|
||||
|
||||
Environment variable | Purpose
|
||||
--------------------------|---------
|
||||
HTTP_PROXY | Proxy address to use when initiating HTTP connection(s)
|
||||
HTTPS_PROXY | Proxy address to use when initiating HTTPS connection(s)
|
||||
NO_PROXY | Network address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s)
|
||||
|
||||
> **Note** NO_PROXY must be in uppercase to use network range (CIDR) notation.
|
||||
|
||||
## Kubernetes installation
|
||||
|
||||
When using Kubernetes installation, the environment variables need to be added to the RKE Config File template.
|
||||
|
||||
* [Kubernetes Installation with External Load Balancer (TCP/Layer 4) RKE Config File Template](layer-4-lb/layer-4-lb.md#5-download-rke-config-file-template)
|
||||
* [Kubernetes Installation with External Load Balancer (HTTPS/Layer 7) RKE Config File Template](layer-7-lb/layer-7-lb.md#5-download-rke-config-file-template)
|
||||
|
||||
The environment variables should be defined in the `Deployment` inside the RKE Config File Template. You only have to add the part starting with `env:` to (but not including) `ports:`. Make sure the indentation is identical to the preceding `name:`. Required values for `NO_PROXY` are:
|
||||
|
||||
* `localhost`
|
||||
* `127.0.0.1`
|
||||
* `0.0.0.0`
|
||||
* Configured `service_cluster_ip_range` (default: `10.43.0.0/16`)
|
||||
|
||||
The example below is based on a proxy server accessible at `http://192.168.0.1:3128`, and excluding usage of the proxy when accessing network range `192.168.10.0/24`, the configured `service_cluster_ip_range` (`10.43.0.0/16`) and every hostname under the domain `example.com`. If you have changed the `service_cluster_ip_range`, you have to update the value below accordingly.
|
||||
|
||||
```yaml
|
||||
...
|
||||
---
|
||||
kind: Deployment
|
||||
apiVersion: extensions/v1beta1
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: cattle
|
||||
spec:
|
||||
serviceAccountName: cattle-admin
|
||||
containers:
|
||||
- image: rancher/rancher:latest
|
||||
imagePullPolicy: Always
|
||||
name: cattle-server
|
||||
env:
|
||||
- name: HTTP_PROXY
|
||||
value: "http://192.168.10.1:3128"
|
||||
- name: HTTPS_PROXY
|
||||
value: "http://192.168.10.1:3128"
|
||||
- name: NO_PROXY
|
||||
value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,192.168.10.0/24,example.com"
|
||||
ports:
|
||||
...
|
||||
```
|
||||
-15
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: RKE Add-On Install
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
|
||||
* [Kubernetes installation with External Load Balancer (TCP/Layer 4)](../../rke-add-on/layer-4-lb.md)
|
||||
* [Kubernetes installation with External Load Balancer (HTTPS/Layer 7)](../../rke-add-on/layer-7-lb.md)
|
||||
* [HTTP Proxy Configuration for a Kubernetes installation](proxy.md)
|
||||
* [Troubleshooting RKE Add-on Installs](troubleshooting/troubleshooting.md)
|
||||
-45
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: 404 - default backend
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
To debug issues around this error, you will need to download the command-line tool `kubectl`. See [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) how to download `kubectl` for your platform.
|
||||
|
||||
When you have made changes to `rancher-cluster.yml`, you will have to run `rke remove --config rancher-cluster.yml` to clean the nodes, so it cannot conflict with previous configuration errors.
|
||||
|
||||
### Possible causes
|
||||
|
||||
The nginx ingress controller is not able to serve the configured host in `rancher-cluster.yml`. This should be the FQDN you configured to access Rancher. You can check if it is properly configured by viewing the ingress that is created by running the following command:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get ingress -n cattle-system -o wide
|
||||
```
|
||||
|
||||
Check if the `HOSTS` column is displaying the FQDN you configured in the template, and that the used nodes are listed in the `ADDRESS` column. If that is configured correctly, we can check the logging of the nginx ingress controller.
|
||||
|
||||
The logging of the nginx ingress controller will show why it cannot serve the requested host. To view the logs, you can run the following command
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=ingress-nginx -n ingress-nginx
|
||||
```
|
||||
|
||||
<b>Errors</b>
|
||||
|
||||
* `x509: certificate is valid for fqdn, not your_configured_fqdn`
|
||||
|
||||
The used certificates do not contain the correct hostname. Generate new certificates that contain the chosen FQDN to access Rancher and redeploy.
|
||||
|
||||
* `Port 80 is already in use. Please check the flag --http-port`
|
||||
|
||||
There is a process on the node occupying port 80, this port is needed for the nginx ingress controller to route requests to Rancher. You can find the process by running the command: `netstat -plant | grep \:80`.
|
||||
|
||||
Stop/kill the process and redeploy.
|
||||
|
||||
* `unexpected error creating pem file: no valid PEM formatted block found`
|
||||
|
||||
The base64 encoded string configured in the template is not valid. Please check if you can decode the configured string using `base64 -D STRING`, this should return the same output as the content of the file you used to generate the string. If this is correct, please check if the base64 encoded string is placed directly after the key, without any newlines before, in between or after. (For example: `tls.crt: LS01..`)
|
||||
-158
@@ -1,158 +0,0 @@
|
||||
---
|
||||
title: Generic troubleshooting
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
Below are steps that you can follow to determine what is wrong in your cluster.
|
||||
|
||||
### Double check if all the required ports are opened in your (host) firewall
|
||||
|
||||
Double check if all the [required ports](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) are opened in your (host) firewall.
|
||||
|
||||
### All nodes should be present and in **Ready** state
|
||||
|
||||
To check, run the command:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get nodes
|
||||
```
|
||||
|
||||
If a node is not shown in this output or a node is not in **Ready** state, you can check the logging of the `kubelet` container. Login to the node and run `docker logs kubelet`.
|
||||
|
||||
### All pods/jobs should be in **Running**/**Completed** state
|
||||
|
||||
To check, run the command:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get pods --all-namespaces
|
||||
```
|
||||
|
||||
If a pod is not in **Running** state, you can dig into the root cause by running:
|
||||
|
||||
#### Describe pod
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml describe pod POD_NAME -n NAMESPACE
|
||||
```
|
||||
|
||||
#### Pod container logs
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs POD_NAME -n NAMESPACE
|
||||
```
|
||||
|
||||
If a job is not in **Completed** state, you can dig into the root cause by running:
|
||||
|
||||
#### Describe job
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml describe job JOB_NAME -n NAMESPACE
|
||||
```
|
||||
|
||||
#### Logs from the containers of pods of the job
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l job-name=JOB_NAME -n NAMESPACE
|
||||
```
|
||||
|
||||
### Check ingress
|
||||
|
||||
Ingress should have the correct `HOSTS` (showing the configured FQDN) and `ADDRESS` (address(es) it will be routed to).
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get ingress --all-namespaces
|
||||
```
|
||||
|
||||
### List all Kubernetes cluster events
|
||||
|
||||
Kubernetes cluster events are stored, and can be retrieved by running:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get events --all-namespaces
|
||||
```
|
||||
|
||||
### Check Rancher container logging
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=cattle -n cattle-system
|
||||
```
|
||||
|
||||
### Check NGINX ingress controller logging
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=ingress-nginx -n ingress-nginx
|
||||
```
|
||||
|
||||
### Check if overlay network is functioning correctly
|
||||
|
||||
The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from `NODE_1` to `NODE_2`. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.
|
||||
|
||||
To test the overlay network, you can launch the following `DaemonSet` definition. This will run an `alpine` container on every host, which we will use to run a `ping` test between containers on all hosts.
|
||||
|
||||
1. Save the following file as `ds-alpine.yml`
|
||||
|
||||
```
|
||||
apiVersion: apps/v1
|
||||
kind: DaemonSet
|
||||
metadata:
|
||||
name: alpine
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
name: alpine
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
name: alpine
|
||||
spec:
|
||||
tolerations:
|
||||
- effect: NoExecute
|
||||
key: "node-role.kubernetes.io/etcd"
|
||||
value: "true"
|
||||
- effect: NoSchedule
|
||||
key: "node-role.kubernetes.io/controlplane"
|
||||
value: "true"
|
||||
containers:
|
||||
- image: alpine
|
||||
imagePullPolicy: Always
|
||||
name: alpine
|
||||
command: ["sh", "-c", "tail -f /dev/null"]
|
||||
terminationMessagePath: /dev/termination-log
|
||||
```
|
||||
|
||||
2. Launch it using `kubectl --kubeconfig kube_config_rancher-cluster.yml create -f ds-alpine.yml`
|
||||
3. Wait until `kubectl --kubeconfig kube_config_rancher-cluster.yml rollout status ds/alpine -w` returns: `daemon set "alpine" successfully rolled out`.
|
||||
4. Run the following command to let each container on every host ping each other (it's a single line command).
|
||||
|
||||
```
|
||||
echo "=> Start"; kubectl --kubeconfig kube_config_rancher-cluster.yml get pods -l name=alpine -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' | while read spod shost; do kubectl --kubeconfig kube_config_rancher-cluster.yml get pods -l name=alpine -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' | while read tip thost; do kubectl --kubeconfig kube_config_rancher-cluster.yml --request-timeout='10s' exec $spod -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $shost cannot reach $thost; fi; done; done; echo "=> End"
|
||||
```
|
||||
|
||||
5. When this command has finished running, the output indicating everything is correct is:
|
||||
|
||||
```
|
||||
=> Start
|
||||
=> End
|
||||
```
|
||||
|
||||
If you see error in the output, that means that the [required ports](../../../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md#networking-requirements) for overlay networking are not opened between the hosts indicated.
|
||||
|
||||
Example error output of a situation where NODE1 had the UDP ports blocked.
|
||||
|
||||
```
|
||||
=> Start
|
||||
command terminated with exit code 1
|
||||
NODE2 cannot reach NODE1
|
||||
command terminated with exit code 1
|
||||
NODE3 cannot reach NODE1
|
||||
command terminated with exit code 1
|
||||
NODE1 cannot reach NODE2
|
||||
command terminated with exit code 1
|
||||
NODE1 cannot reach NODE3
|
||||
=> End
|
||||
```
|
||||
-59
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Failed to get job complete status
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
To debug issues around this error, you will need to download the command-line tool `kubectl`. See [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) how to download `kubectl` for your platform.
|
||||
|
||||
When you have made changes to `rancher-cluster.yml`, you will have to run `rke remove --config rancher-cluster.yml` to clean the nodes, so it cannot conflict with previous configuration errors.
|
||||
|
||||
### Failed to deploy addon execute job [rke-user-includes-addons]: Failed to get job complete status
|
||||
|
||||
Something is wrong in the addons definitions, you can run the following command to get the root cause in the logging of the job:
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l job-name=rke-user-addon-deploy-job -n kube-system
|
||||
```
|
||||
|
||||
#### error: error converting YAML to JSON: yaml: line 9:
|
||||
|
||||
The structure of the addons definition in `rancher-cluster.yml` is wrong. In the different resources specified in the addons section, there is a error in the structure of the YAML. The pointer `yaml line 9` references to the line number of the addon that is causing issues.
|
||||
|
||||
<b>Things to check</b>
|
||||
<ul>
|
||||
<ul>
|
||||
<li>Is each of the base64 encoded certificate string placed directly after the key, for example: `tls.crt: LS01...`, there should be no newline/space before, in between or after.</li>
|
||||
<li>Is the YAML properly formatted, each indentation should be 2 spaces as shown in the template files.</li>
|
||||
<li>Verify the integrity of your certificate by running this command `cat MyCertificate | base64 -d` on Linux, `cat MyCertificate | base64 -D` on Mac OS . If any error exists, the command output will tell you.</li>
|
||||
</ul>
|
||||
</ul>
|
||||
|
||||
#### Error from server (BadRequest): error when creating "/etc/config/rke-user-addon.yaml": Secret in version "v1" cannot be handled as a Secret
|
||||
|
||||
The base64 string of one of the certificate strings is wrong. The log message will try to show you what part of the string is not recognized as valid base64.
|
||||
|
||||
<b>Things to check</b>
|
||||
<ul>
|
||||
<ul>
|
||||
<li>Check if the base64 string is valid by running one of the commands below:</li>
|
||||
|
||||
```
|
||||
# MacOS
|
||||
echo BASE64_CRT | base64 -D
|
||||
# Linux
|
||||
echo BASE64_CRT | base64 -d
|
||||
# Windows
|
||||
certutil -decode FILENAME.base64 FILENAME.verify
|
||||
```
|
||||
|
||||
</ul>
|
||||
</ul>
|
||||
|
||||
#### The Ingress "cattle-ingress-http" is invalid: spec.rules[0].host: Invalid value: "IP": must be a DNS name, not an IP address
|
||||
|
||||
The host value can only contain a host name, as it is needed by the ingress controller to match the hostname and pass to the correct backend.
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting HA RKE Add-On Install
|
||||
---
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install ](../../../../../resources/helm-version-requirements.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
This section contains common errors seen when setting up a Kubernetes installation.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
- [Generic troubleshooting](generic-troubleshooting.md)
|
||||
|
||||
In this section, you can find generic ways to debug your Kubernetes cluster.
|
||||
|
||||
- [Failed to set up SSH tunneling for host](https://rancher.com/docs/rke/latest/en/troubleshooting/ssh-connectivity-errors/)
|
||||
|
||||
In this section, you can find errors related to SSH tunneling when you run the `rke` command to setup your nodes.
|
||||
|
||||
- [Failed to get job complete status](job-complete-status.md)
|
||||
|
||||
In this section, you can find errors related to deploying addons.
|
||||
|
||||
- [404 - default backend](404-default-backend.md)
|
||||
|
||||
In this section, you can find errors related to the `404 - default backend` page that is shown when trying to access Rancher.
|
||||
-113
@@ -1,113 +0,0 @@
|
||||
---
|
||||
title: Opening Ports with firewalld
|
||||
---
|
||||
|
||||
:::danger
|
||||
|
||||
Enabling firewalld can cause serious network communication problems.
|
||||
|
||||
CNIs in Kubernetes dynamically update iptables and networking rules independently of any external firewalls, such as firewalld. This can cause unexpected behavior when the CNI and the external firewall conflict.
|
||||
|
||||
:::
|
||||
|
||||
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](../../installation-requirements/port-requirements.md) 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.
|
||||
-381
@@ -1,381 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (TCP/Layer 4)
|
||||
---
|
||||
import SSlFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:
|
||||
|
||||
- Layer 4 load balancer (TCP)
|
||||
- [NGINX ingress controller with SSL termination (HTTPS)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In an HA setup that uses a layer 4 load balancer, the load balancer accepts Rancher client connections over the TCP/UDP protocols (i.e., the transport level). The load balancer then forwards these connections to individual cluster nodes without reading the request itself. Because the load balancer cannot read the packets it's forwarding, the routing decisions it can make are limited.
|
||||
|
||||
<sup>Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at ingress controllers</sup>
|
||||
|
||||
|
||||
|
||||
## Installation Outline
|
||||
|
||||
Installation of Rancher in a high-availability configuration involves multiple procedures. Review this outline to learn about each procedure you need to complete.
|
||||
|
||||
|
||||
<br/>
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
We will be using NGINX as our Layer 4 Load Balancer (TCP). NGINX will forward all connections to one of your Rancher nodes. If you want to use Amazon NLB, you can skip this step and use [Amazon NLB configuration](../../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)
|
||||
|
||||
>**Note:**
|
||||
> In this configuration, the load balancer is positioned in front of your Linux hosts. The load balancer can be any host that you have available that's capable of running NGINX.
|
||||
>
|
||||
>One caveat: do not use one of your Rancher nodes as the load balancer.
|
||||
|
||||
### A. Install NGINX
|
||||
|
||||
Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems. For help installing NGINX, refer to their [install documentation](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 how to install and enable the NGINX `stream` module on your operating system.
|
||||
|
||||
### B. Create NGINX Configuration
|
||||
|
||||
After installing NGINX, you need to update the NGINX config 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 `IP_NODE_1`, `IP_NODE_2`, and `IP_NODE_3` with the IPs of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
>**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/).
|
||||
|
||||
**Example NGINX config:**
|
||||
```
|
||||
worker_processes 4;
|
||||
worker_rlimit_nofile 40000;
|
||||
|
||||
events {
|
||||
worker_connections 8192;
|
||||
}
|
||||
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
stream {
|
||||
upstream rancher_servers {
|
||||
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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE Config File Template
|
||||
|
||||
RKE uses a `.yml` config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.
|
||||
|
||||
1. Download one of following templates, depending on the SSL certificate you're using.
|
||||
|
||||
- [Template for self-signed certificate<br/>](../cluster-yml-templates/node-certificate.md)
|
||||
- [Template for certificate signed by recognized CA<br/> ](../cluster-yml-templates/node-certificate-recognizedca.md)
|
||||
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
> When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) >for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in base64.
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
1. In `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
2. In `kind: Secret` with `name: cattle-keys-server`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`).
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
|
||||
**Step Result:** The file should look like the example below (the base64 encoded string should be different):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the intermediate certificates in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included.
|
||||
|
||||
In the `kind: Secret` with `name: cattle-keys-ingress`:
|
||||
|
||||
* Replace `<BASE64_CRT>` with the base64 encoded string of the Certificate file (usually called `cert.pem` or `domain.crt`)
|
||||
* Replace `<BASE64_KEY>` with the base64 encoded string of the Certificate Key file (usually called `key.pem` or `domain.key`)
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
>**Note:**
|
||||
> The base64 encoded string should be on the same line as `tls.crt` or `tls.key`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-ingress
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
|
||||
tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There are two references to `<FQDN>` in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
In the `kind: Ingress` with `name: cattle-ingress-http`:
|
||||
|
||||
* Replace `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns).
|
||||
|
||||
After replacing `<FQDN>` with the FQDN chosen in [Configure DNS](#3-configure-dns), the file should look like the example below (`rancher.yourdomain.com` is the FQDN used in this example):
|
||||
|
||||
```yaml
|
||||
---
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: rancher.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
tls:
|
||||
- secretName: cattle-keys-ingress
|
||||
hosts:
|
||||
- rancher.yourdomain.com
|
||||
```
|
||||
|
||||
Save the `.yml` file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](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.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** The output should be similar to the snippet below:
|
||||
|
||||
```
|
||||
INFO[0000] Building Kubernetes cluster
|
||||
INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
|
||||
INFO[0000] [network] Deploying port listener containers
|
||||
INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
|
||||
...
|
||||
INFO[0101] Finished building Kubernetes cluster successfully
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
You have a couple of options:
|
||||
|
||||
- Create a backup of your Rancher Server in case of a disaster scenario: [High Availability Back Up and Restore](../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md).
|
||||
- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
-271
@@ -1,271 +0,0 @@
|
||||
---
|
||||
title: Kubernetes Install with External Load Balancer (HTTPS/Layer 7)
|
||||
---
|
||||
import SslFaqHa from '@site/src/components/SslFaqHa'
|
||||
|
||||
> #### **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../../../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md).
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, see [Migrating from a Kubernetes Install with an RKE Add-on](../../../install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
|
||||
This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:
|
||||
|
||||
- Layer 7 load balancer with SSL termination (HTTPS)
|
||||
- [NGINX Ingress controller (HTTP)](https://kubernetes.github.io/ingress-nginx/)
|
||||
|
||||
In an HA setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.
|
||||
|
||||
<sup>Rancher installed on a Kubernetes cluster with layer 7 load balancer, depicting SSL termination at load balancer</sup>
|
||||
|
||||
|
||||
|
||||
## Installation Outline
|
||||
|
||||
Installation of Rancher in a high-availability configuration involves multiple procedures. Review this outline to learn about each procedure you need to complete.
|
||||
|
||||
## 1. Provision Linux Hosts
|
||||
|
||||
Provision three Linux hosts according to our [Requirements](../../../installation-requirements/installation-requirements.md).
|
||||
|
||||
## 2. Configure Load Balancer
|
||||
|
||||
When using a load balancer in front of Rancher, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto: https`, this redirect is disabled. This is the expected configuration when terminating SSL externally.
|
||||
|
||||
The load balancer has to be configured to support the following:
|
||||
|
||||
* **WebSocket** connections
|
||||
* **SPDY** / **HTTP/2** protocols
|
||||
* Passing / setting the following headers:
|
||||
|
||||
| Header | Value | Description |
|
||||
|---------------------|----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `Host` | FQDN 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.<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. |
|
||||
| `X-Forwarded-For` | IP of the client connection. | To identify the originating IP address of a client. |
|
||||
|
||||
Health checks can be executed on the `/healthz` endpoint of the node, this will return HTTP 200.
|
||||
|
||||
We have example configurations for the following load balancers:
|
||||
|
||||
* [Amazon ELB configuration](../../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)
|
||||
* [NGINX configuration](../../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)
|
||||
|
||||
## 3. Configure DNS
|
||||
|
||||
Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., `rancher.yourdomain.com`).<br/><br/>
|
||||
|
||||
1. Log into your DNS server a create a `DNS A` record that points to the IP address of your [load balancer](#2-configure-load-balancer).
|
||||
|
||||
2. Validate that the `DNS A` is working correctly. Run the following command from any terminal, replacing `HOSTNAME.DOMAIN.COM` with your chosen FQDN:
|
||||
|
||||
`nslookup HOSTNAME.DOMAIN.COM`
|
||||
|
||||
**Step Result:** Terminal displays output similar to the following:
|
||||
|
||||
```
|
||||
$ nslookup rancher.yourdomain.com
|
||||
Server: YOUR_HOSTNAME_IP_ADDRESS
|
||||
Address: YOUR_HOSTNAME_IP_ADDRESS#53
|
||||
|
||||
Non-authoritative answer:
|
||||
Name: rancher.yourdomain.com
|
||||
Address: HOSTNAME.DOMAIN.COM
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
## 4. Install RKE
|
||||
|
||||
RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.
|
||||
|
||||
1. Follow the [RKE Install](https://rancher.com/docs/rke/latest/en/installation) instructions.
|
||||
|
||||
2. Confirm that RKE is now executable by running the following command:
|
||||
|
||||
```
|
||||
rke --version
|
||||
```
|
||||
|
||||
## 5. Download RKE Config File Template
|
||||
|
||||
RKE uses a YAML config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.
|
||||
|
||||
1. Download one of following templates, depending on the SSL certificate you're using.
|
||||
|
||||
- [Template for self-signed certificate<br/> `3-node-externalssl-certificate.yml`](../cluster-yml-templates/node-externalssl-certificate.md)installation/options/cluster-yml-templates/3-node-externalssl-certificate)
|
||||
- [Template for certificate signed by recognized CA<br/> `3-node-externalssl-recognizedca.yml`](../cluster-yml-templates/node-externalssl-recognizedca.md)
|
||||
|
||||
|
||||
|
||||
2. Rename the file to `rancher-cluster.yml`.
|
||||
|
||||
## 6. Configure Nodes
|
||||
|
||||
Once you have the `rancher-cluster.yml` config file template, edit the nodes section to point toward your Linux hosts.
|
||||
|
||||
1. Open `rancher-cluster.yml` in your favorite text editor.
|
||||
|
||||
1. Update the `nodes` section with the information of your [Linux hosts](#1-provision-linux-hosts).
|
||||
|
||||
For each node in your cluster, update the following placeholders: `IP_ADDRESS_X` and `USER`. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run `docker ps`.
|
||||
|
||||
>**Note:**
|
||||
>
|
||||
>When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See [Operating System Requirements](https://rancher.com/docs/rke/latest/en/installation/os#redhat-enterprise-linux-rhel-centos) for RHEL/CentOS specific requirements.
|
||||
|
||||
nodes:
|
||||
# The IP address or hostname of the node
|
||||
- address: IP_ADDRESS_1
|
||||
# User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
|
||||
# When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
# Path the SSH key that can be used to access to node with the specified user
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_2
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
- address: IP_ADDRESS_3
|
||||
user: USER
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: ~/.ssh/id_rsa
|
||||
|
||||
1. **Optional:** By default, `rancher-cluster.yml` is configured to take backup snapshots of your data. To disable these snapshots, change the `backup` directive setting to `false`, as depicted below.
|
||||
|
||||
services:
|
||||
etcd:
|
||||
backup: false
|
||||
|
||||
## 7. Configure Certificates
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Option A—Bring Your Own Certificate: Self-Signed</summary>
|
||||
|
||||
>**Prerequisites:**
|
||||
>Create a self-signed certificate.
|
||||
>
|
||||
>- The certificate files must be in PEM format.
|
||||
>- The certificate files must be encoded in base64.
|
||||
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../../../other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
In `kind: Secret` with `name: cattle-keys-ingress`, replace `<BASE64_CA>` with the base64 encoded string of the CA Certificate file (usually called `ca.pem` or `ca.crt`)
|
||||
|
||||
>**Note:** The base64 encoded string should be on the same line as `cacerts.pem`, without any newline at the beginning, in between or at the end.
|
||||
|
||||
After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: cattle-keys-server
|
||||
namespace: cattle-system
|
||||
type: Opaque
|
||||
data:
|
||||
cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
|
||||
|
||||
</details>
|
||||
<details id="option-b">
|
||||
<summary>Option B—Bring Your Own Certificate: Signed by Recognized CA</summary>
|
||||
|
||||
If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part.
|
||||
|
||||
</details>
|
||||
|
||||
## 8. Configure FQDN
|
||||
|
||||
There is one reference to `<FQDN>` in the RKE config file. Replace this reference with the FQDN you chose in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
1. Open `rancher-cluster.yml`.
|
||||
|
||||
2. In the `kind: Ingress` with `name: cattle-ingress-http:`
|
||||
|
||||
Replace `<FQDN>` with the FQDN chosen in [3. Configure DNS](#3-configure-dns).
|
||||
|
||||
**Step Result:** After replacing the values, the file should look like the example below (the base64 encoded strings should be different):
|
||||
|
||||
```
|
||||
apiVersion: extensions/v1beta1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
namespace: cattle-system
|
||||
name: cattle-ingress-http
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
|
||||
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # Max time in seconds for ws to remain shell window open
|
||||
spec:
|
||||
rules:
|
||||
- host: rancher.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- backend:
|
||||
serviceName: cattle-service
|
||||
servicePort: 80
|
||||
```
|
||||
|
||||
|
||||
3. Save the file and close it.
|
||||
|
||||
## 9. Configure Rancher version
|
||||
|
||||
The last reference that needs to be replaced is `<RANCHER_VERSION>`. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the [GitHub README](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.
|
||||
|
||||
## 11. Run RKE
|
||||
|
||||
With all configuration in place, use RKE to launch Rancher. You can complete this action by running the `rke up` command and using the `--config` parameter to point toward your config file.
|
||||
|
||||
1. From your workstation, make sure `rancher-cluster.yml` and the downloaded `rke` binary are in the same directory.
|
||||
|
||||
2. Open a Terminal instance. Change to the directory that contains your config file and `rke`.
|
||||
|
||||
3. Enter one of the `rke up` commands listen below.
|
||||
|
||||
```
|
||||
rke up --config rancher-cluster.yml
|
||||
```
|
||||
|
||||
**Step Result:** The output should be similar to the snippet below:
|
||||
|
||||
```
|
||||
INFO[0000] Building Kubernetes cluster
|
||||
INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
|
||||
INFO[0000] [network] Deploying port listener containers
|
||||
INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
|
||||
...
|
||||
INFO[0101] Finished building Kubernetes cluster successfully
|
||||
```
|
||||
|
||||
## 12. Back Up Auto-Generated Config File
|
||||
|
||||
During installation, RKE automatically generates a config file named `kube_config_rancher-cluster.yml` in the same directory as the `rancher-cluster.yml` file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **Recommended:** Review [Creating Backups—High Availability Back Up and Restoration](../../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) to learn how to backup your Rancher Server in case of a disaster scenario.
|
||||
- Create a Kubernetes cluster: [Creating a Cluster](../../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<br/>
|
||||
|
||||
## FAQ and Troubleshooting
|
||||
|
||||
<SslFaqHa/>
|
||||
-6
@@ -1,6 +0,0 @@
|
||||
---
|
||||
title: RKE Add-On Install
|
||||
---
|
||||
|
||||
- [Kubernetes Install with External Load Balancer (TCP/Layer 4)](layer-4-lb.md)
|
||||
- [Kubernetes Install with External Load Balancer (HTTPS/Layer 7)](layer-7-lb.md)
|
||||
-39
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Tuning etcd for Large Installations
|
||||
---
|
||||
|
||||
When running larger Rancher installations with 15 or more clusters it is recommended to increase the default keyspace for etcd from the default 2GB. The maximum setting is 8GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval.
|
||||
|
||||
The etcd data set is automatically cleaned up on a five minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see `mvcc: database space exceeded` errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the [quota-backend-bytes](https://etcd.io/docs/v3.3/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.3/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 striping RAID configurations to increase available IOPS.
|
||||
|
||||
To implement this solution in an RKE cluster, the `/var/lib/etcd/data` and `/var/lib/etcd/wal` directories will need to have disks mounted and formatted on the underlying host. In the `extra_args` directive of the `etcd` service, you must include the `wal_dir` directory. Without specifying the `wal_dir`, etcd process will try to manipulate the underlying `wal` mount with insufficient permissions.
|
||||
|
||||
```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'
|
||||
```
|
||||
-139
@@ -1,139 +0,0 @@
|
||||
---
|
||||
title: Enabling Experimental Features
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/enable-experimental-features"/>
|
||||
</head>
|
||||
|
||||
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](unsupported-storage-drivers.md) 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) in Rancher v2.3.3+ 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. See the [feature flags page](../../../../reference-guides/installation-references/feature-flags.md) for more information.
|
||||
|
||||
## Enabling Features when Starting Rancher
|
||||
|
||||
When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.
|
||||
|
||||
> **Note:** Values set from the Rancher API will override the value passed in through the command line.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install">
|
||||
|
||||
When installing Rancher with a Helm chart, use the `--features` option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:
|
||||
|
||||
```
|
||||
helm install rancher-latest/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
Note: If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
### Rendering the Helm Chart for Air Gap Installations
|
||||
|
||||
For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the [air gap installation documentation.](../../other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.md)
|
||||
|
||||
Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.
|
||||
|
||||
The Helm 3 command is as follows:
|
||||
|
||||
```
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
The Helm 2 command is as follows:
|
||||
|
||||
```
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
|
||||
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
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 # Available as of v2.3.0
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Enabling Features with the Rancher UI
|
||||
|
||||
1. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. You will see a list of experimental features.
|
||||
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. Go to the **Global** view and click **Settings.**
|
||||
1. Click the **Feature Flags** tab. 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.
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: UI for Istio Virtual Services and Destination Rules
|
||||
---
|
||||
|
||||
This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.
|
||||
|
||||
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster](../../../../how-to-guides/advanced-user-guides/istio-setup-guide/istio-setup-guide.md) in order to use the feature.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](../../../../reference-guides/installation-references/feature-flags.md)
|
||||
|
||||
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. Go to the project view in Rancher and click **Resources > Istio.**
|
||||
1. You will see tabs for **Traffic Graph,** which has the Kiali network visualization integrated into the UI, and **Traffic Metrics,** which shows metrics for the success rate and request volume of traffic to your services, among other metrics. Next to these tabs, you should see the tabs for **Virtual Services** and **Destination Rules.**
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: "Running on ARM64 (Experimental)"
|
||||
---
|
||||
|
||||
> **Important:**
|
||||
>
|
||||
> Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment.
|
||||
|
||||
The following options are available when using an ARM64 platform:
|
||||
|
||||
- Running Rancher on ARM64 based node(s)
|
||||
- Only for Docker Install. Please note that the following installation command replaces the examples found in the [Docker Install](../../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) 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](../../../../faq/container-network-interface-providers.md#flannel)
|
||||
|
||||
- Importing clusters that contain ARM64 based nodes
|
||||
- Kubernetes cluster version must be 1.12 or higher
|
||||
|
||||
Please see [Cluster Options](../../../../reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.md) for information on how to configure the cluster options.
|
||||
|
||||
The following features are not tested:
|
||||
|
||||
- Monitoring, alerts, notifiers, pipelines and logging
|
||||
- Launching apps from the catalog
|
||||
-39
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Allowing Unsupported Storage Drivers
|
||||
---
|
||||
|
||||
This feature allows you to use types for storage providers and provisioners that are not enabled by default.
|
||||
|
||||
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.](../../../../reference-guides/installation-references/feature-flags.md)
|
||||
|
||||
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`
|
||||
-296
@@ -1,296 +0,0 @@
|
||||
---
|
||||
title: Install Rancher on a Kubernetes Cluster
|
||||
description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster"/>
|
||||
</head>
|
||||
|
||||
## Prerequisite
|
||||
|
||||
Set up the Rancher server's local Kubernetes cluster.
|
||||
|
||||
The cluster requirements depend on the Rancher version:
|
||||
|
||||
- **In Rancher v2.4.x,** Rancher needs to be installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.
|
||||
- **In Rancher before v2.4,** Rancher needs to be installed on an RKE Kubernetes cluster.
|
||||
|
||||
For the tutorial to install an RKE Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.md) For help setting up the infrastructure for a high-availability RKE cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.md)
|
||||
|
||||
For the tutorial to install a K3s Kubernetes cluster, refer to [this page.](../../../how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.md) For help setting up the infrastructure for a high-availability K3s cluster, refer to [this page.](../../../how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.md)
|
||||
|
||||
## Install the Rancher Helm Chart
|
||||
|
||||
Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents.
|
||||
|
||||
With Helm, we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.
|
||||
|
||||
For systems without direct internet access, see [Air Gap: Kubernetes install](../advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.md).
|
||||
|
||||
To choose a Rancher version to install, refer to [Choosing a Rancher Version.](../resources/choose-a-rancher-version.md)
|
||||
|
||||
To choose a version of Helm to install Rancher with, refer to the [Helm version requirements](../resources/helm-version-requirements.md)
|
||||
|
||||
> **Note:** The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) This [section](../resources/helm-version-requirements.md) provides a copy of the older installation instructions for Rancher installed on an RKE Kubernetes cluster with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
To set up Rancher,
|
||||
|
||||
1. [Install the required CLI tools](#1-install-the-required-cli-tools)
|
||||
2. [Add the Helm chart repository](#2-add-the-helm-chart-repository)
|
||||
3. [Create a namespace for Rancher](#3-create-a-namespace-for-rancher)
|
||||
4. [Choose your SSL configuration](#4-choose-your-ssl-configuration)
|
||||
5. [Install cert-manager](#5-install-cert-manager) (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
|
||||
6. [Install Rancher with Helm and your chosen certificate option](#6-install-rancher-with-helm-and-your-chosen-certificate-option)
|
||||
7. [Verify that the Rancher server is successfully deployed](#7-verify-that-the-rancher-server-is-successfully-deployed)
|
||||
8. [Save your options](#8-save-your-options)
|
||||
|
||||
### 1. Install the Required CLI Tools
|
||||
|
||||
The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your `$PATH`.
|
||||
|
||||
Refer to the [instructions provided by the Helm project](https://helm.sh/docs/intro/install/) for your specific platform.
|
||||
|
||||
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
|
||||
- [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements](../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
### 2. Add the Helm Chart Repository
|
||||
|
||||
Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Rancher Version](../resources/choose-a-rancher-version.md).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
### 3. Create a Namespace for Rancher
|
||||
|
||||
We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be `cattle-system`:
|
||||
|
||||
```
|
||||
kubectl create namespace cattle-system
|
||||
```
|
||||
|
||||
### 4. Choose your SSL Configuration
|
||||
|
||||
The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:
|
||||
|
||||
- **Rancher-generated TLS certificate:** In this case, you will need to install `cert-manager` into the cluster. Rancher utilizes `cert-manager` to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. `cert-manager` is then responsible for managing that certificate.
|
||||
- **Let's Encrypt:** The Let's Encrypt option also uses `cert-manager`. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (`HTTP-01`), so the load balancer must have a public DNS record and be accessible from the internet.
|
||||
- **Bring your own certificate:** This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name `tls.crt` and `tls.key`. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
|
||||
|
||||
|
||||
| Configuration | Helm Chart Option | Requires cert-manager |
|
||||
| ------------------------------ | ----------------------- | ------------------------------------- |
|
||||
| Rancher Generated Certificates (Default) | `ingress.tls.source=rancher` | [yes](#5-install-cert-manager) |
|
||||
| Let’s Encrypt | `ingress.tls.source=letsEncrypt` | [yes](#5-install-cert-manager) |
|
||||
| Certificates from Files | `ingress.tls.source=secret` | no |
|
||||
|
||||
### 5. Install cert-manager
|
||||
|
||||
> You should skip this step if you are bringing your own certificate files (option `ingress.tls.source=secret`), or if you use [TLS termination on an external load balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
This step is only required to use certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) or to request Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`).
|
||||
|
||||
<details id="cert-manager">
|
||||
<summary>Click to Expand</summary>
|
||||
|
||||
> **Important:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade documentation](../resources/upgrade-cert-manager.md).
|
||||
|
||||
These instructions are adapted from the [official cert-manager documentation](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm).
|
||||
|
||||
```
|
||||
# Install the CustomResourceDefinition resources separately
|
||||
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
|
||||
|
||||
# **Important:**
|
||||
# If you are running Kubernetes v1.15 or below, you
|
||||
# will need to add the `--validate=false` flag to your
|
||||
# kubectl apply command, or else you will receive a
|
||||
# validation error relating to the
|
||||
# x-kubernetes-preserve-unknown-fields field in
|
||||
# cert-manager’s CustomResourceDefinition resources.
|
||||
# This is a benign error and occurs due to the way kubectl
|
||||
# performs resource validation.
|
||||
|
||||
# Create the namespace for cert-manager
|
||||
kubectl create namespace cert-manager
|
||||
|
||||
# Add the Jetstack Helm repository
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
|
||||
# Update your local Helm chart repository cache
|
||||
helm repo update
|
||||
|
||||
# Install the cert-manager Helm chart
|
||||
helm install \
|
||||
cert-manager jetstack/cert-manager \
|
||||
--namespace cert-manager \
|
||||
--version v1.0.4
|
||||
```
|
||||
|
||||
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
|
||||
|
||||
```
|
||||
kubectl get pods --namespace cert-manager
|
||||
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
cert-manager-5c6866597-zw7kh 1/1 Running 0 2m
|
||||
cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m
|
||||
cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 6. Install Rancher with Helm and Your Chosen Certificate Option
|
||||
|
||||
The exact command to install Rancher differs depending on the certificate configuration.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Rancher-generated Certificates">
|
||||
|
||||
The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command.
|
||||
|
||||
- Set the `hostname` to the DNS name you pointed at your load balancer.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
- To install a specific Rancher version, use the `--version` flag, example: `--version 2.3.6`
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Let's Encrypt">
|
||||
|
||||
This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA.
|
||||
|
||||
In the following command,
|
||||
|
||||
- `hostname` is set to the public DNS record,
|
||||
- `ingress.tls.source` is set to `letsEncrypt`
|
||||
- `letsEncrypt.email` is set to the email address used for communication about your certificate (for example, expiry notices)
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=letsEncrypt \
|
||||
--set letsEncrypt.email=me@example.org \
|
||||
```
|
||||
|
||||
Wait for Rancher to be rolled out:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Certificates from Files">
|
||||
|
||||
In this option, Kubernetes secrets are created from your own certificates for Rancher to use.
|
||||
|
||||
When you run this command, the `hostname` option must match the `Common Name` or a `Subject Alternative Names` entry in the server certificate or the Ingress controller will fail to configure correctly.
|
||||
|
||||
Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers and applications.
|
||||
|
||||
> If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?](../../../faq/technical-items.md#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate)
|
||||
|
||||
- Set the `hostname`.
|
||||
- Set `ingress.tls.source` to `secret`.
|
||||
- If you are installing an alpha version, Helm requires adding the `--devel` option to the command.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret
|
||||
```
|
||||
|
||||
If you are using a Private CA signed certificate , add `--set privateCA=true` to the command:
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true
|
||||
```
|
||||
|
||||
Now that Rancher is deployed, see [Adding TLS Secrets](../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the Ingress controller can use them.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.
|
||||
|
||||
- [HTTP Proxy](../../../reference-guides/installation-references/helm-chart-options.md#http-proxy)
|
||||
- [Private Docker Image Registry](../../../reference-guides/installation-references/helm-chart-options.md#private-registry-and-air-gap-installs)
|
||||
- [TLS Termination on an External Load Balancer](../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
|
||||
See the [Chart Options](../../../reference-guides/installation-references/helm-chart-options.md) for the full list of options.
|
||||
|
||||
|
||||
### 7. Verify that the Rancher Server is Successfully Deployed
|
||||
|
||||
After adding the secrets, check if Rancher was rolled out successfully:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system rollout status deploy/rancher
|
||||
Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
|
||||
deployment "rancher" successfully rolled out
|
||||
```
|
||||
|
||||
If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command:
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get deploy rancher
|
||||
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
|
||||
rancher 3 3 3 3 3m
|
||||
```
|
||||
|
||||
It should show the same count for `DESIRED` and `AVAILABLE`.
|
||||
|
||||
### 8. Save Your Options
|
||||
|
||||
Make sure you save the `--set` options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.
|
||||
|
||||
### Finishing Up
|
||||
|
||||
That's it. You should have a functional Rancher server.
|
||||
|
||||
In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.
|
||||
|
||||
Doesn't work? Take a look at the [Troubleshooting](troubleshooting.md) Page
|
||||
|
||||
|
||||
### Optional Next Steps
|
||||
|
||||
Enable the Enterprise Cluster Manager.
|
||||
-86
@@ -1,86 +0,0 @@
|
||||
---
|
||||
title: Rollbacks
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks"/>
|
||||
</head>
|
||||
|
||||
### Rolling Back to Rancher v2.2-v2.4
|
||||
|
||||
For Rancher installed on Kubernetes, follow the procedure detailed here: [Restoring Backups for Kubernetes installs.](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.md) Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot.
|
||||
|
||||
For information on how to roll back Rancher installed with Docker, refer to [this page.](../other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.md)
|
||||
|
||||
> Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.
|
||||
|
||||
### Rolling Back to v2.0.0-v2.1.5
|
||||
|
||||
If you are rolling back to versions in either of these scenarios, you must follow some extra instructions in order to get your clusters working.
|
||||
|
||||
- Rolling back from v2.1.6+ to any version between v2.1.0 - v2.1.5 or v2.0.0 - v2.0.10.
|
||||
- Rolling back from v2.0.11+ to any version between v2.0.0 - v2.0.10.
|
||||
|
||||
Because of the changes necessary to address [CVE-2018-20321](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-20321), special steps are necessary if the user wants to roll back to a previous version of Rancher where this vulnerability exists. The steps are as follows:
|
||||
|
||||
1. Record the `serviceAccountToken` for each cluster. To do this, save the following script on a machine with `kubectl` access to the Rancher management plane and execute it. You will need to run these commands on the machine where the rancher container is running. Ensure JQ is installed before running the command. The commands will vary depending on how you installed Rancher.
|
||||
|
||||
**Rancher Installed with Docker**
|
||||
```
|
||||
docker exec <NAME OF RANCHER CONTAINER> kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json
|
||||
```
|
||||
|
||||
**Rancher Installed on a Kubernetes Cluster**
|
||||
```
|
||||
kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json
|
||||
```
|
||||
|
||||
2. After executing the command a `tokens.json` file will be created. Important! Back up this file in a safe place.** You will need it to restore functionality to your clusters after rolling back Rancher. **If you lose this file, you may lose access to your clusters.**
|
||||
|
||||
3. Rollback Rancher following the [normal instructions](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md).
|
||||
|
||||
4. Once Rancher comes back up, every cluster managed by Rancher (except for Imported clusters) will be in an `Unavailable` state.
|
||||
|
||||
5. Apply the backed up tokens based on how you installed Rancher.
|
||||
|
||||
**Rancher Installed with Docker**
|
||||
|
||||
Save the following script as `apply_tokens.sh` to the machine where the Rancher docker container is running. Also copy the `tokens.json` file created previously to the same directory as the script.
|
||||
```
|
||||
set -e
|
||||
|
||||
tokens=$(jq .[] -c tokens.json)
|
||||
for token in $tokens; do
|
||||
name=$(echo $token | jq -r .name)
|
||||
value=$(echo $token | jq -r .token)
|
||||
|
||||
docker exec $1 kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
|
||||
done
|
||||
```
|
||||
the script to allow execution (`chmod +x apply_tokens.sh`) and execute the script as follows:
|
||||
```
|
||||
./apply_tokens.sh <DOCKER CONTAINER NAME>
|
||||
```
|
||||
After a few moments the clusters will go from Unavailable back to Available.
|
||||
|
||||
**Rancher Installed on a Kubernetes Cluster**
|
||||
|
||||
Save the following script as `apply_tokens.sh` to a machine with kubectl access to the Rancher management plane. Also copy the `tokens.json` file created previously to the same directory as the script.
|
||||
```
|
||||
set -e
|
||||
|
||||
tokens=$(jq .[] -c tokens.json)
|
||||
for token in $tokens; do
|
||||
name=$(echo $token | jq -r .name)
|
||||
value=$(echo $token | jq -r .token)
|
||||
|
||||
kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
|
||||
done
|
||||
```
|
||||
Set the script to allow execution (`chmod +x apply_tokens.sh`) and execute the script as follows:
|
||||
```
|
||||
./apply_tokens.sh
|
||||
```
|
||||
After a few moments the clusters will go from `Unavailable` back to `Available`.
|
||||
|
||||
6. Continue using Rancher as normal.
|
||||
-188
@@ -1,188 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting the Rancher Server Kubernetes Cluster
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting"/>
|
||||
</head>
|
||||
|
||||
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-23) 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`.
|
||||
-229
@@ -1,229 +0,0 @@
|
||||
---
|
||||
title: Upgrading Rancher Installed on Kubernetes with Helm 2
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades"/>
|
||||
</head>
|
||||
|
||||
> Helm 3 has been released. If you are using Helm 2, we recommend [migrating to Helm 3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) because it is simpler to use and more secure than Helm 2.
|
||||
>
|
||||
> The [current instructions for Upgrading Rancher Installed on Kubernetes](upgrades.md) use Helm 3.
|
||||
>
|
||||
> This section provides a copy of the older instructions for upgrading Rancher with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
The following instructions will guide you through using Helm to upgrade a Rancher server that is installed on a Kubernetes cluster.
|
||||
|
||||
To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services](https://rancher.com/docs/rke/latest/en/config-options/services/) or [add-ons](https://rancher.com/docs/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE](https://rancher.com/docs/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
|
||||
|
||||
If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade](./migrating-from-rke-add-on.md).
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
> - [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) Upgrade cert-manager to the latest version by following [these instructions.](../../resources/upgrade-cert-manager.md)
|
||||
> - If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.](../../../../reference-guides/installation-references/helm-chart-options.md#configuring-ingress-for-external-tls-when-using-nginx-v025)
|
||||
> - The upgrade instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) This [section](../../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Review the [known upgrade issues](upgrades.md)** in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
- **For [air gap installs only,](../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version.** Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
## Upgrade Outline
|
||||
|
||||
Follow the steps to upgrade Rancher server:
|
||||
|
||||
- [A. Back up your Kubernetes cluster that is running Rancher server](#a-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
|
||||
- [B. Update the Helm chart repository](#b-update-the-helm-chart-repository)
|
||||
- [C. Upgrade Rancher](#c-upgrade-rancher)
|
||||
- [D. Verify the Upgrade](#d-verify-the-upgrade)
|
||||
|
||||
### A. Back up Your Kubernetes Cluster that is Running Rancher Server
|
||||
|
||||
[Take a one-time snapshot](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#option-b-one-time-snapshots)
|
||||
of your Kubernetes cluster running Rancher server. You'll use the snapshot as a restore point if something goes wrong during upgrade.
|
||||
|
||||
### B. Update the Helm chart repository
|
||||
|
||||
1. Update your local Helm repo cache.
|
||||
|
||||
```
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Get the repository name that you used to install Rancher.
|
||||
|
||||
For information about the repos and their differences, see [Helm Chart Repositories](../../resources/choose-a-rancher-version.md#helm-chart-repositories).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
```
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://charts.helm.sh/stable
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
> **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories](../../resources/choose-a-rancher-version.md#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
|
||||
|
||||
|
||||
1. Fetch the latest chart to install Rancher from the Helm chart repository.
|
||||
|
||||
This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
|
||||
### C. Upgrade Rancher
|
||||
|
||||
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Upgrade">
|
||||
|
||||
Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
|
||||
|
||||
```
|
||||
helm get values rancher
|
||||
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** There will be more values that are listed with this command. This is just an example of one of the values.
|
||||
|
||||
If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow `Option B: Reinstalling Rancher`. Otherwise, follow `Option A: Upgrading Rancher`.
|
||||
|
||||
<details>
|
||||
<summary>Option A: Upgrading Rancher</summary>
|
||||
|
||||
Upgrade Rancher to the latest version with all your settings.
|
||||
|
||||
Take all the values from the previous step and append them to the command using `--set key=value`. Note: There will be many more options from the previous step that need to be appended.
|
||||
|
||||
```
|
||||
helm upgrade --install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Option B: Reinstalling Rancher chart</summary>
|
||||
|
||||
If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.
|
||||
|
||||
1. Uninstall Rancher
|
||||
|
||||
```
|
||||
helm delete rancher
|
||||
```
|
||||
In case this results in an error that the release "rancher" was not found, make sure you are using the correct deployment name. Use `helm list` to list the helm-deployed releases.
|
||||
|
||||
2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager](../../resources/upgrade-cert-manager-helm-2.md) page.
|
||||
|
||||
3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
|
||||
|
||||
```
|
||||
helm install rancher-<CHART_REPO>/rancher \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Kubernetes Air Gap Upgrade">
|
||||
|
||||
1. Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
Based on the choice you made during installation, complete one of the procedures below.
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
<details id="self-signed">
|
||||
<summary>Option A-Default Self-Signed Certificate</summary>
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
</details>
|
||||
<details id="secret">
|
||||
<summary>Option B: Certificates From Files using Kubernetes Secrets</summary>
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
2. Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
|
||||
|
||||
Use `kubectl` to apply the rendered manifests.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### D. Verify the Upgrade
|
||||
|
||||
Log into Rancher to confirm that the upgrade succeeded.
|
||||
|
||||
>**Having network issues following upgrade?**
|
||||
>
|
||||
> See [Restoring Cluster Networking](namespace-migration.md#restoring-cluster-networking).
|
||||
|
||||
## Rolling Back
|
||||
|
||||
Should something go wrong, follow the [roll back](../rollbacks.md) instructions to restore the snapshot you took before you preformed the upgrade.
|
||||
-105
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Migrating from a Kubernetes Install with an RKE Add-on
|
||||
---
|
||||
|
||||
> **Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
>
|
||||
>If you are currently using the RKE add-on install method, please follow these directions to migrate to the Helm install.
|
||||
|
||||
|
||||
The following instructions will help guide you through migrating from the RKE Add-on install to managing Rancher with the Helm package manager.
|
||||
|
||||
You will need the to have [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) installed and the kubeconfig YAML file (`kube_config_rancher-cluster.yml`) generated by RKE.
|
||||
|
||||
> **Note:** This guide assumes a standard Rancher install. If you have modified any of the object names or namespaces, please adjust accordingly.
|
||||
|
||||
> **Note:** If you are upgrading from from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your cluster's certificates have expired, you will need to perform [additional steps](../../../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
|
||||
### Point kubectl at your Rancher Cluster
|
||||
|
||||
Make sure `kubectl` is using the correct kubeconfig YAML file. Set the `KUBECONFIG` environmental variable to point to `kube_config_rancher-cluster.yml`:
|
||||
|
||||
```
|
||||
export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml
|
||||
```
|
||||
|
||||
After setting the `KUBECONFIG` environment variable, verify that it contains the correct `server` parameter. It should point directly to one of your cluster nodes on port `6443`.
|
||||
|
||||
```
|
||||
kubectl config view -o=jsonpath='{.clusters[*].cluster.server}'
|
||||
https://NODE:6443
|
||||
```
|
||||
|
||||
If the output from the command shows your Rancher hostname with the suffix `/k8s/clusters`, the wrong kubeconfig YAML file is configured. It should be the file that was created when you used RKE to create the cluster to run Rancher.
|
||||
|
||||
### Save your certificates
|
||||
|
||||
If you have terminated ssl on the Rancher cluster ingress, recover your certificate and key for use in the Helm install.
|
||||
|
||||
Use `kubectl` to get the secret, decode the value and direct the output to a file.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.crt }' | base64 -d > tls.crt
|
||||
kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.key }' | base64 -d > tls.key
|
||||
```
|
||||
|
||||
If you specified a private CA root cert
|
||||
|
||||
```
|
||||
kubectl -n cattle-system get secret cattle-keys-server -o jsonpath --template='{ .data.cacerts\.pem }' | base64 -d > cacerts.pem
|
||||
```
|
||||
|
||||
### Remove previous Kubernetes objects
|
||||
|
||||
Remove the Kubernetes objects created by the RKE install.
|
||||
|
||||
> **Note:** Removing these Kubernetes components will not affect the Rancher configuration or database, but with any maintenance it is a good idea to create a backup of the data before hand. See [Creating Backups-Kubernetes Install](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md) for details.
|
||||
|
||||
```
|
||||
kubectl -n cattle-system delete ingress cattle-ingress-http
|
||||
kubectl -n cattle-system delete service cattle-service
|
||||
kubectl -n cattle-system delete deployment cattle
|
||||
kubectl -n cattle-system delete clusterrolebinding cattle-crb
|
||||
kubectl -n cattle-system delete serviceaccount cattle-admin
|
||||
```
|
||||
|
||||
### Remove addons section from `rancher-cluster.yml`
|
||||
|
||||
The addons section from `rancher-cluster.yml` contains all the resources needed to deploy Rancher using RKE. By switching to Helm, this part of the cluster configuration file is no longer needed. Open `rancher-cluster.yml` in your favorite text editor and remove the addons section:
|
||||
|
||||
>**Important:** Make sure you only remove the addons section from the cluster configuration file.
|
||||
|
||||
```
|
||||
nodes:
|
||||
- address: <IP> # hostname or IP to access nodes
|
||||
user: <USER> # root user (usually 'root')
|
||||
role: [controlplane,etcd,worker] # K8s roles for node
|
||||
ssh_key_path: <PEM_FILE> # path to PEM file
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
- address: <IP>
|
||||
user: <USER>
|
||||
role: [controlplane,etcd,worker]
|
||||
ssh_key_path: <PEM_FILE>
|
||||
|
||||
services:
|
||||
etcd:
|
||||
snapshot: true
|
||||
creation: 6h
|
||||
retention: 24h
|
||||
|
||||
# Remove addons section from here til end of file
|
||||
addons: |-
|
||||
---
|
||||
...
|
||||
# End of file
|
||||
```
|
||||
|
||||
### Follow Helm and Rancher install steps
|
||||
|
||||
From here follow the standard install steps.
|
||||
|
||||
* [3 - Initialize Helm](../../advanced-options/advanced-use-cases/helm2/helm-init/helm-init.md)
|
||||
* [4 - Install Rancher](../../advanced-options/advanced-use-cases/helm2/helm-rancher/helm-rancher.md)
|
||||
-187
@@ -1,187 +0,0 @@
|
||||
---
|
||||
title: Upgrading to v2.0.7+ — Namespace Migration
|
||||
---
|
||||
|
||||
>This section applies only to Rancher upgrades from v2.0.6 or earlier to v2.0.7 or later. Upgrades from v2.0.7 to later version are unaffected.
|
||||
|
||||
In Rancher v2.0.6 and prior, system namespaces crucial for Rancher and Kubernetes operations were not assigned to any Rancher project by default. Instead, these namespaces existed independently from all Rancher projects, but you could move these namespaces into any project without affecting cluster operations.
|
||||
|
||||
These namespaces include:
|
||||
|
||||
- `kube-system`
|
||||
- `kube-public`
|
||||
- `cattle-system`
|
||||
- `cattle-alerting`<sup>1</sup>
|
||||
- `cattle-logging`<sup>1</sup>
|
||||
- `cattle-pipeline`<sup>1</sup>
|
||||
- `ingress-nginx`
|
||||
|
||||
><sup>1</sup> Only displays if this feature is enabled for the cluster.
|
||||
|
||||
However, with the release of Rancher v2.0.7, the `System` project was introduced. This project, which is automatically created during the upgrade, is assigned the system namespaces above to hold these crucial components for safe keeping.
|
||||
|
||||
During upgrades from Rancher v2.0.6- to Rancher v2.0.7+, all system namespaces are moved from their default location outside of all projects into the newly created `System` project. However, if you assigned any of your system namespaces to a project before upgrading, your cluster networking may encounter issues afterwards. This issue occurs because the system namespaces are not where the upgrade expects them to be during the upgrade, so it cannot move them to the `System` project.
|
||||
|
||||
- To prevent this issue from occurring before the upgrade, see [Preventing Cluster Networking Issues](#preventing-cluster-networking-issues).
|
||||
- To fix this issue following upgrade, see [Restoring Cluster Networking](#restoring-cluster-networking).
|
||||
|
||||
> **Note:** If you are upgrading from from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your cluster's certificates have expired, you will need to perform [additional steps](../../../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
|
||||
## Preventing Cluster Networking Issues
|
||||
|
||||
You can prevent cluster networking issues from occurring during your upgrade to v2.0.7+ by unassigning system namespaces from all of your Rancher projects. Complete this task if you've assigned any of a cluster's system namespaces into a Rancher project.
|
||||
|
||||
1. Log into the Rancher UI before upgrade.
|
||||
|
||||
1. From the context menu, open the **local** cluster (or any of your other clusters).
|
||||
|
||||
1. From the main menu, select **Project/Namespaces**.
|
||||
|
||||
1. Find and select the following namespaces. Click **Move** and then choose **None** to move them out of your projects. Click **Move** again.
|
||||
|
||||
>**Note:** Some or all of these namespaces may already be unassigned from all projects.
|
||||
|
||||
- `kube-system`
|
||||
- `kube-public`
|
||||
- `cattle-system`
|
||||
- `cattle-alerting`<sup>1</sup>
|
||||
- `cattle-logging`<sup>1</sup>
|
||||
- `cattle-pipeline`<sup>1</sup>
|
||||
- `ingress-nginx`
|
||||
|
||||
><sup>1</sup> Only displays if this feature is enabled for the cluster.
|
||||
|
||||
<figcaption>Moving namespaces out of projects</figcaption>
|
||||
|
||||
|
||||
1. Repeat these steps for each cluster where you've assigned system namespaces to projects.
|
||||
|
||||
**Result:** All system namespaces are moved out of Rancher projects. You can now safely begin the [upgrade](upgrades.md).
|
||||
|
||||
## Restoring Cluster Networking
|
||||
|
||||
Reset the cluster nodes' network policies to restore connectivity.
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>Download and setup [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install">
|
||||
|
||||
1. From **Terminal**, change directories to your kubectl file that's generated during Rancher install, `kube_config_rancher-cluster.yml`. This file is usually in the directory where you ran RKE during Rancher installation.
|
||||
|
||||
1. Before repairing networking, run the following two commands to make sure that your nodes have a status of `Ready` and that your cluster components are `Healthy`.
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get nodes
|
||||
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
165.227.114.63 Ready controlplane,etcd,worker 11m v1.10.1
|
||||
165.227.116.167 Ready controlplane,etcd,worker 11m v1.10.1
|
||||
165.227.127.226 Ready controlplane,etcd,worker 11m v1.10.1
|
||||
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get cs
|
||||
|
||||
NAME STATUS MESSAGE ERROR
|
||||
scheduler Healthy ok
|
||||
controller-manager Healthy ok
|
||||
etcd-0 Healthy {"health": "true"}
|
||||
etcd-2 Healthy {"health": "true"}
|
||||
etcd-1 Healthy {"health": "true"}
|
||||
```
|
||||
|
||||
1. Check the `networkPolicy` for all clusters by running the following command.
|
||||
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o=custom-columns=ID:.metadata.name,NAME:.spec.displayName,NETWORKPOLICY:.spec.enableNetworkPolicy,APPLIEDNP:.status.appliedSpec.enableNetworkPolicy,ANNOTATION:.metadata.annotations."networking\.management\.cattle\.io/enable-network-policy"
|
||||
|
||||
ID NAME NETWORKPOLICY APPLIEDNP ANNOTATION
|
||||
c-59ptz custom <nil> <nil> <none>
|
||||
local local <nil> <nil> <none>
|
||||
|
||||
|
||||
1. Disable the `networkPolicy` for all clusters, still pointing toward your `kube_config_rancher-cluster.yml`.
|
||||
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o jsonpath='{range .items[*]}{@.metadata.name}{"\n"}{end}' | xargs -I {} kubectl --kubeconfig kube_config_rancher-cluster.yml patch cluster {} --type merge -p '{"spec": {"enableNetworkPolicy": false},"status": {"appliedSpec": {"enableNetworkPolicy": false }}}'
|
||||
|
||||
>**Tip:** If you want to keep `networkPolicy` enabled for all created clusters, you can run the following command to disable `networkPolicy` for `local` cluster (i.e., your Rancher Server nodes):
|
||||
>
|
||||
>```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml patch cluster local --type merge -p '{"spec": {"enableNetworkPolicy": false},"status": {"appliedSpec": {"enableNetworkPolicy": false }}}'
|
||||
```
|
||||
|
||||
1. Remove annotations for network policy for all clusters
|
||||
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o jsonpath='{range .items[*]}{@.metadata.name}{"\n"}{end}' | xargs -I {} kubectl --kubeconfig kube_config_rancher-cluster.yml annotate cluster {} "networking.management.cattle.io/enable-network-policy"="false" --overwrite
|
||||
|
||||
>**Tip:** If you want to keep `networkPolicy` enabled for all created clusters, you can run the following command to disable `networkPolicy` for `local` cluster (i.e., your Rancher Server nodes):
|
||||
>
|
||||
>```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml annotate cluster local "networking.management.cattle.io/enable-network-policy"="false" --overwrite
|
||||
```
|
||||
|
||||
1. Check the `networkPolicy` for all clusters again to make sure the policies have a status of `false `.
|
||||
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o=custom-columns=ID:.metadata.name,NAME:.spec.displayName,NETWORKPOLICY:.spec.enableNetworkPolicy,APPLIEDNP:.status.appliedSpec.enableNetworkPolicy,ANNOTATION:.metadata.annotations."networking\.management\.cattle\.io/enable-network-policy"
|
||||
|
||||
ID NAME NETWORKPOLICY APPLIEDNP ANNOTATION
|
||||
c-59ptz custom false false false
|
||||
local local false false false
|
||||
|
||||
1. Remove all network policies from all namespaces. Run this command for each cluster, using the kubeconfig generated by RKE.
|
||||
|
||||
```
|
||||
for namespace in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get ns -o custom-columns=NAME:.metadata.name --no-headers); do
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml -n $namespace delete networkpolicy --all;
|
||||
done
|
||||
```
|
||||
|
||||
1. Remove all the projectnetworkpolicies created for the clusters, to make sure networkpolicies are not recreated.
|
||||
|
||||
```
|
||||
for cluster in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get clusters -o custom-columns=NAME:.metadata.name --no-headers); do
|
||||
for project in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get project -n $cluster -o custom-columns=NAME:.metadata.name --no-headers); do
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml delete projectnetworkpolicy -n $project --all
|
||||
done
|
||||
done
|
||||
```
|
||||
|
||||
>**Tip:** If you want to keep `networkPolicy` enabled for all created clusters, you can run the following command to disable `networkPolicy` for `local` cluster (i.e., your Rancher Server nodes):
|
||||
>
|
||||
>```
|
||||
for project in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get project -n local -o custom-columns=NAME:.metadata.name --no-headers); do
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml -n $project delete projectnetworkpolicy --all;
|
||||
done
|
||||
```
|
||||
|
||||
1. Wait a few minutes and then log into the Rancher UI.
|
||||
|
||||
- If you can access Rancher, you're done, so you can skip the rest of the steps.
|
||||
- If you still can't access Rancher, complete the steps below.
|
||||
|
||||
1. Force your pods to recreate themselves by entering the following command.
|
||||
|
||||
```
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml delete pods -n cattle-system --all
|
||||
```
|
||||
|
||||
1. Log into the Rancher UI and view your clusters. Created clusters will show errors from attempting to contact Rancher while it was unavailable. However, these errors should resolve automatically.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Rancher Launched Kubernetes">
|
||||
|
||||
If you can access Rancher, but one or more of the clusters that you launched using Rancher has no networking, you can repair them by moving them:
|
||||
|
||||
- Using the cluster's [embedded kubectl shell](../../../../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-shell-in-the-rancher-ui).
|
||||
- By [downloading the cluster kubeconfig file and running it](../../../../how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.md#accessing-clusters-with-kubectl-from-your-workstation) from your workstation.
|
||||
|
||||
```
|
||||
for namespace in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get ns -o custom-columns=NAME:.metadata.name --no-headers); do
|
||||
kubectl --kubeconfig kube_config_rancher-cluster.yml -n $namespace delete networkpolicy --all;
|
||||
done
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
-283
@@ -1,283 +0,0 @@
|
||||
---
|
||||
title: Upgrades
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades"/>
|
||||
</head>
|
||||
|
||||
The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.
|
||||
|
||||
For the instructions to upgrade Rancher installed with Docker, refer to [this page.](../../other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md)
|
||||
|
||||
To upgrade the components in your Kubernetes cluster, or the definition of the [Kubernetes services](https://rancher.com/docs/rke/latest/en/config-options/services/) or [add-ons](https://rancher.com/docs/rke/latest/en/config-options/add-ons/), refer to the [upgrade documentation for RKE](https://rancher.com/docs/rke/latest/en/upgrades/), the Rancher Kubernetes Engine.
|
||||
|
||||
If you installed Rancher using the RKE Add-on yaml, follow the directions to [migrate or upgrade](migrating-from-rke-add-on.md).
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Upgrade Outline](#upgrade-outline)
|
||||
- [Known Upgrade Issues](#known-upgrade-issues)
|
||||
- [RKE Add-on Installs](#rke-add-on-installs)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Access to kubeconfig
|
||||
|
||||
Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.
|
||||
|
||||
If you installed Kubernetes with RKE, the config will have been created in the directory you ran `rke up` in.
|
||||
|
||||
The kubeconfig can also be manually targeted for the intended cluster with the `--kubeconfig` tag (see: https://helm.sh/docs/helm/helm/)
|
||||
|
||||
### Review Known Issues
|
||||
|
||||
Review the [known upgrade issues](#known-upgrade-issues) in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.
|
||||
|
||||
A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported.
|
||||
|
||||
### Helm Version
|
||||
|
||||
The upgrade instructions assume you are using Helm 3.
|
||||
|
||||
For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](helm2.md)provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
|
||||
|
||||
### For air gap installs: Populate private registry
|
||||
|
||||
-For [air gap installs only,](../../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
|
||||
|
||||
### For upgrades from v2.0-v2.2 with external TLS termination
|
||||
|
||||
If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to [enable using forwarded host headers.](../../../../reference-guides/installation-references/helm-chart-options.md#configuring-ingress-for-external-tls-when-using-nginx-v025)
|
||||
|
||||
### For upgrades with cert-manager older than 0.8.0
|
||||
|
||||
[Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) Upgrade cert-manager to the latest version by following [these instructions.](../../resources/upgrade-cert-manager.md)
|
||||
|
||||
## Upgrade Outline
|
||||
|
||||
Follow the steps to upgrade Rancher server:
|
||||
|
||||
- [1. Back up your Kubernetes cluster that is running Rancher server](#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server)
|
||||
- [2. Update the Helm chart repository](#2-update-the-helm-chart-repository)
|
||||
- [3. Upgrade Rancher](#3-upgrade-rancher)
|
||||
- [4. Verify the Upgrade](#4-verify-the-upgrade)
|
||||
|
||||
## 1. Back up Your Kubernetes Cluster that is Running Rancher Server
|
||||
|
||||
|
||||
[Take a one-time snapshot](../../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.md#option-b-one-time-snapshots)
|
||||
of your Kubernetes cluster running Rancher server.
|
||||
|
||||
You'll use the backup as a restoration point if something goes wrong during upgrade.
|
||||
|
||||
## 2. Update the Helm chart repository
|
||||
|
||||
1. Update your local Helm repo cache:
|
||||
|
||||
```
|
||||
helm repo update
|
||||
```
|
||||
|
||||
1. Get the repository name that you used to install Rancher.
|
||||
|
||||
For information about the repos and their differences, see [Helm Chart Repositories](../../resources/choose-a-rancher-version.md#helm-chart-repositories).
|
||||
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
```
|
||||
helm repo list
|
||||
|
||||
NAME URL
|
||||
stable https://charts.helm.sh/stable
|
||||
rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
|
||||
```
|
||||
|
||||
> **Note:** If you want to switch to a different Helm chart repository, please follow the [steps on how to switch repositories](../../resources/choose-a-rancher-version.md#switching-to-a-different-helm-chart-repository). If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.
|
||||
|
||||
1. Fetch the latest chart to install Rancher from the Helm chart repository.
|
||||
|
||||
This command will pull down the latest charts and save it in the current directory as a `.tgz` file.
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
You can fetch the chart for the specific version you are upgrading to by adding in the `--version=` tag. For example:
|
||||
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11
|
||||
```
|
||||
|
||||
## 3. Upgrade Rancher
|
||||
|
||||
This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Upgrade">
|
||||
|
||||
Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed.
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system
|
||||
|
||||
hostname: rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** There will be more values that are listed with this command. This is just an example of one of the values.
|
||||
|
||||
If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow [Option B: Reinstalling Rancher and cert-manager.](#option-b-reinstalling-rancher-and-cert-manager)
|
||||
|
||||
Otherwise, follow [Option A: Upgrading Rancher.](#option-a-upgrading-rancher)
|
||||
|
||||
### Option A: Upgrading Rancher
|
||||
|
||||
Upgrade Rancher to the latest version with all your settings.
|
||||
|
||||
Take all the values from the previous step and append them to the command using `--set key=value`:
|
||||
|
||||
```
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
> **Note:** The above is an example, there may be more values from the previous step that need to be appended.
|
||||
|
||||
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
|
||||
|
||||
```
|
||||
helm get values rancher -n cattle-system -o yaml > values.yaml
|
||||
|
||||
helm upgrade rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
-f values.yaml \
|
||||
--version=2.4.5
|
||||
```
|
||||
|
||||
### Option B: Reinstalling Rancher and cert-manager
|
||||
|
||||
If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.
|
||||
|
||||
1. Uninstall Rancher
|
||||
|
||||
```
|
||||
helm delete rancher -n cattle-system
|
||||
```
|
||||
|
||||
2. Uninstall and reinstall `cert-manager` according to the instructions on the [Upgrading Cert-Manager](../../resources/upgrade-cert-manager-helm-2.md) page.
|
||||
|
||||
3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using `--set key=value`. Note: There will be many more options from the step 1 that need to be appended.
|
||||
|
||||
```
|
||||
helm install rancher rancher-<CHART_REPO>/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=rancher.my.org
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Kubernetes Air Gap Upgrade">
|
||||
|
||||
Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
Based on the choice you made during installation, complete one of the procedures below.
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
### Option A: Default Self-signed Certificate
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Option B: Certificates from Files using Kubernetes Secrets
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--name rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
### Apply the Rendered Templates
|
||||
|
||||
Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.
|
||||
|
||||
Use `kubectl` to apply the rendered manifests.
|
||||
|
||||
```plain
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 4. Verify the Upgrade
|
||||
|
||||
Log into Rancher to confirm that the upgrade succeeded.
|
||||
|
||||
>**Having network issues following upgrade?**
|
||||
>
|
||||
> See [Restoring Cluster Networking](namespace-migration.md#restoring-cluster-networking).
|
||||
|
||||
## Known Upgrade Issues
|
||||
|
||||
The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
|
||||
|
||||
Upgrade Scenario | Issue
|
||||
---|---
|
||||
Upgrading to v2.4.6 or v2.4.7 | These Rancher versions had an issue where the `kms:ListKeys` permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
|
||||
Upgrading to v2.3.0+ | Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
|
||||
Upgrading to v2.2.0-v2.2.x | Rancher introduced the [system charts](https://github.com/rancher/system-charts) repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the `system-charts` repository locally and configure Rancher to use that repository. Please follow the instructions to [configure Rancher system charts](../../resources/local-system-charts.md).
|
||||
Upgrading from v2.0.13 or earlier | If your cluster's certificates have expired, you will need to perform [additional steps](../../../../how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.md#rotating-expired-certificates-after-upgrading-older-rancher-versions) to rotate the certificates.
|
||||
Upgrading from v2.0.7 or earlier | Rancher introduced the `system` project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to [prevent cluster networking issues.](namespace-migration.md)
|
||||
|
||||
## RKE Add-on Installs
|
||||
|
||||
**Important: RKE add-on install is only supported up to Rancher v2.0.8**
|
||||
|
||||
Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the [Kubernetes Install](../install-upgrade-on-a-kubernetes-cluster.md).
|
||||
|
||||
If you are currently using the RKE add-on install method, see [Migrating from a RKE add-on install](migrating-from-rke-add-on.md) for details on how to start using the Helm chart.
|
||||
-96
@@ -1,96 +0,0 @@
|
||||
---
|
||||
title: Installing/Upgrading Rancher
|
||||
description: Learn how to install Rancher in development and production environments. Read about single node and high availability installation
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade"/>
|
||||
</head>
|
||||
|
||||
This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.
|
||||
|
||||
## Terminology
|
||||
|
||||
In this section,
|
||||
|
||||
- **The Rancher server** manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface.
|
||||
- **RKE (Rancher Kubernetes Engine)** is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster.
|
||||
- **K3s (Lightweight Kubernetes)** is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster.
|
||||
|
||||
## Overview of Installation Options
|
||||
|
||||
Rancher can be installed on these main architectures:
|
||||
|
||||
### High-availability Kubernetes Install with the Helm CLI
|
||||
|
||||
We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required.
|
||||
|
||||
### Single-node Kubernetes Install
|
||||
|
||||
Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't have high availability, which is important for running Rancher in production.
|
||||
|
||||
However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server.
|
||||
|
||||
### Docker Install
|
||||
|
||||
For test and demonstration purposes, Rancher can be installed with Docker on a single node.
|
||||
|
||||
For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
|
||||
### Other Options
|
||||
|
||||
There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy:
|
||||
|
||||
| Level of Internet Access | Kubernetes Installation - Strongly Recommended | Docker Installation |
|
||||
| ---------------------------------- | ------------------------------ | ---------- |
|
||||
| With direct access to the Internet | [Docs](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) | [Docs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) |
|
||||
| Behind an HTTP proxy | These [docs,](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) plus this [configuration](../../reference-guides/installation-references/helm-chart-options.md#http-proxy) | These [docs,](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) plus this [configuration](../../reference-guides/single-node-rancher-in-docker/http-proxy-configuration.md) |
|
||||
| In an air gap environment | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) | [Docs](other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) |
|
||||
|
||||
We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage.
|
||||
|
||||
For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters.
|
||||
|
||||
> The type of cluster that Rancher needs to be installed on depends on the Rancher version.
|
||||
>
|
||||
> For Rancher v2.4.x, either an RKE Kubernetes cluster or K3s Kubernetes cluster can be used.
|
||||
> For Rancher before v2.4, an RKE cluster must be used.
|
||||
|
||||
For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only.
|
||||
|
||||
Our [instructions for installing Rancher on Kubernetes](install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md) describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster.
|
||||
|
||||
When the nodes in your Kubernetes cluster are running and fulfill the [node requirements,](installation-requirements/installation-requirements.md) you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster.
|
||||
|
||||
For a longer discussion of Rancher architecture, refer to the [architecture overview,](../../reference-guides/rancher-manager-architecture/rancher-manager-architecture.md) [recommendations for production-grade architecture,](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md) or our [best practices guide.](../../reference-guides/best-practices/deployment-types.md)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing Rancher, make sure that your nodes fulfill all of the [installation requirements.](installation-requirements/installation-requirements.md)
|
||||
|
||||
## Architecture Tip
|
||||
|
||||
For the best performance and greater security, we recommend a separate, dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can [create or import clusters](../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) for running your workloads.
|
||||
|
||||
For more architecture recommendations, refer to [this page.](../../reference-guides/rancher-manager-architecture/architecture-recommendations.md)
|
||||
|
||||
### More Options for Installations on a Kubernetes Cluster
|
||||
|
||||
Refer to the [Helm chart options](../../reference-guides/installation-references/helm-chart-options.md) for details on installing Rancher on a Kubernetes cluster with other configurations, including:
|
||||
|
||||
- With [API auditing to record all transactions](../../reference-guides/installation-references/helm-chart-options.md#api-audit-log)
|
||||
- With [TLS termination on a load balancer](../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
- With a [custom Ingress](../../reference-guides/installation-references/helm-chart-options.md#customizing-your-ingress)
|
||||
|
||||
In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation:
|
||||
|
||||
- [RKE configuration options](https://rancher.com/docs/rke/latest/en/config-options/)
|
||||
- [K3s configuration options](https://rancher.com/docs/k3s/latest/en/installation/install-options/)
|
||||
|
||||
### More Options for Installations with Docker
|
||||
|
||||
Refer to the [docs about options for Docker installs](other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) for details about other configurations including:
|
||||
|
||||
- With [API auditing to record all transactions](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
|
||||
- With an [external load balancer](advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.md)
|
||||
- With a [persistent data store](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#persistent-data)
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Installing Docker
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-requirements/install-docker"/>
|
||||
</head>
|
||||
|
||||
Docker is required to be installed on nodes where the Rancher server will be installed with Helm or Docker.
|
||||
|
||||
There are a couple of options for installing Docker. One option is to refer to the [official Docker documentation](https://docs.docker.com/install/) about how to install Docker on Linux. The steps will vary based on the Linux distribution.
|
||||
|
||||
Another option is to use one of Rancher's Docker installation scripts, which are available for most recent versions of Docker. Rancher has installation scripts for every version of upstream Docker that Kubernetes supports.
|
||||
|
||||
For example, this command could be used to install on one of the main Linux distributions, such as SUSE Linux Enterprise or Ubuntu:
|
||||
|
||||
```bash
|
||||
curl https://releases.rancher.com/install-docker/<version-number>.sh | sh
|
||||
```
|
||||
|
||||
Consult the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions/rancher-v2-4-18/) to match a validated Docker version with your operating system and version of Rancher. Although the support matrix lists validated Docker versions down to the patch version, only the major and minor version of the release are relevant for the Docker installation scripts.
|
||||
-147
@@ -1,147 +0,0 @@
|
||||
---
|
||||
title: Installation Requirements
|
||||
description: Learn the node requirements for each node running Rancher server when you’re configuring Rancher to run either in a Docker or Kubernetes setup
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-requirements"/>
|
||||
</head>
|
||||
|
||||
This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.
|
||||
|
||||
> It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the [node requirements for downstream user clusters,](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.md) which will run your apps and services.
|
||||
|
||||
Make sure the node(s) for the Rancher server fulfill the following requirements:
|
||||
|
||||
- [Operating Systems and Container Runtime Requirements](#operating-systems-and-container-runtime-requirements)
|
||||
- [Hardware Requirements](#hardware-requirements)
|
||||
- [CPU and Memory](#cpu-and-memory)
|
||||
- [CPU and Memory for Rancher before v2.4.0](#cpu-and-memory-for-rancher-before-v240)
|
||||
- [Disks](#disks)
|
||||
- [Networking Requirements](#networking-requirements)
|
||||
- [Node IP Addresses](#node-ip-addresses)
|
||||
- [Port Requirements](#port-requirements)
|
||||
|
||||
For a list of best practices that we recommend for running the Rancher server in production, refer to the [best practices section.](../../../reference-guides/best-practices/deployment-types.md)
|
||||
|
||||
The Rancher UI works best in Firefox or Chrome.
|
||||
|
||||
## Operating Systems and Container Runtime Requirements
|
||||
|
||||
Rancher should work with any modern Linux distribution.
|
||||
|
||||
For details on which OS, Docker, and Kubernetes versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/)
|
||||
|
||||
All supported operating systems are 64-bit x86.
|
||||
|
||||
The `ntp` (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.
|
||||
|
||||
Some distributions of Linux may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.
|
||||
|
||||
If you plan to run Rancher on ARM64, see [Running on ARM64 (Experimental).](../advanced-options/enable-experimental-features/rancher-on-arm64.md)
|
||||
|
||||
### RKE Specific Requirements
|
||||
|
||||
For the container runtime, RKE should work with any modern Docker version.
|
||||
|
||||
### K3s Specific Requirements
|
||||
|
||||
For the container runtime, K3s should work with any modern version of Docker or containerd.
|
||||
|
||||
Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.
|
||||
|
||||
If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables.
|
||||
|
||||
If you are installing Rancher on a K3s cluster with Alpine Linux, follow [these steps](https://rancher.com/docs/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup.
|
||||
|
||||
### Installing Docker
|
||||
|
||||
Docker is required for Helm chart installs, and it can be installed by following the steps in the official [Docker documentation.](https://docs.docker.com/) Rancher also provides [scripts](install-docker.md) to install Docker with one command.
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.
|
||||
|
||||
### CPU and Memory
|
||||
|
||||
Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="RKE">
|
||||
|
||||
These requirements apply to each host in an [RKE Kubernetes cluster where the Rancher server is installed.](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)
|
||||
|
||||
Performance increased in Rancher v2.4.0. For the requirements of Rancher before v2.4.0, refer to [this section.](#cpu-and-memory-for-rancher-before-v240)
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | ---------- | ------------ | -------| ------- |
|
||||
| Small | Up to 150 | Up to 1500 | 2 | 8 GB |
|
||||
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB |
|
||||
| Large | Up to 500 | Up to 5000 | 8 | 32 GB |
|
||||
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB |
|
||||
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB |
|
||||
|
||||
Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="K3s">
|
||||
|
||||
These requirements apply to each host in a [K3s Kubernetes cluster where the Rancher server is installed.](../install-upgrade-on-a-kubernetes-cluster/install-upgrade-on-a-kubernetes-cluster.md)
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM | Database Size |
|
||||
| --------------- | ---------- | ------------ | -------| ---------| ------------------------- |
|
||||
| Small | Up to 150 | Up to 1500 | 2 | 8 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| Medium | Up to 300 | Up to 3000 | 4 | 16 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| Large | Up to 500 | Up to 5000 | 8 | 32 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
| XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS |
|
||||
|
||||
Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours.
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker">
|
||||
|
||||
These requirements apply to a host with a [single-node](../other-installation-methods/rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) installation of Rancher.
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | -------- | --------- | ----- | ---- |
|
||||
| Small | Up to 5 | Up to 50 | 1 | 4 GB |
|
||||
| Medium | Up to 15 | Up to 200 | 2 | 8 GB |
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### CPU and Memory for Rancher before v2.4.0
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
These requirements apply to installing Rancher on an RKE Kubernetes cluster before Rancher v2.4.0:
|
||||
|
||||
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
|
||||
| --------------- | --------- | ---------- | ----------------------------------------------- | ----------------------------------------------- |
|
||||
| Small | Up to 5 | Up to 50 | 2 | 8 GB |
|
||||
| Medium | Up to 15 | Up to 200 | 4 | 16 GB |
|
||||
| Large | Up to 50 | Up to 500 | 8 | 32 GB |
|
||||
| X-Large | Up to 100 | Up to 1000 | 32 | 128 GB |
|
||||
| XX-Large | 100+ | 1000+ | [Contact Rancher](https://rancher.com/contact/) | [Contact Rancher](https://rancher.com/contact/) |
|
||||
</details>
|
||||
|
||||
### Disks
|
||||
|
||||
Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.
|
||||
|
||||
## Networking Requirements
|
||||
|
||||
This section describes the networking requirements for the node(s) where the Rancher server is installed.
|
||||
|
||||
### Node IP Addresses
|
||||
|
||||
Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
|
||||
|
||||
### Port Requirements
|
||||
|
||||
To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. [Port Requirements](port-requirements.md) lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.
|
||||
-258
@@ -1,258 +0,0 @@
|
||||
---
|
||||
title: Port Requirements
|
||||
description: Read about port requirements needed in order for Rancher to operate properly, both for Rancher nodes and downstream Kubernetes cluster nodes
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-requirements/port-requirements"/>
|
||||
</head>
|
||||
|
||||
import PortsIaasNodes from '@site/src/components/PortsIaasNodes'
|
||||
import PortsCustomNodes from '@site/src/components/PortsCustomNodes'
|
||||
import PortsImportedHosted from '@site/src/components/PortsImportedHosted'
|
||||
|
||||
To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.
|
||||
|
||||
## Rancher Nodes
|
||||
|
||||
The following table lists the ports that need to be open to and from nodes that are running the Rancher server.
|
||||
|
||||
The port requirements differ based on the Rancher server architecture.
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> - Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example).
|
||||
> - Kubernetes recommends TCP 30000-32767 for node port services.
|
||||
> - For firewalls, traffic may need to be enabled within the cluster and pod CIDR.
|
||||
|
||||
### Ports for Rancher Server Nodes on K3s
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The K3s server needs port 6443 to be accessible by the nodes.
|
||||
|
||||
The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.
|
||||
|
||||
If you wish to utilize the metrics server, you will need to open port 10250 on each node.
|
||||
|
||||
> **Important:** The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.
|
||||
|
||||
The following tables break down the port requirements for inbound and outbound traffic:
|
||||
|
||||
<figcaption>Inbound Rules for Rancher Server Nodes</figcaption>
|
||||
|
||||
| Protocol | Port | Source | Description
|
||||
|-----|-----|----------------|---|
|
||||
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used |
|
||||
| TCP | 443 | <ul><li>server nodes</li><li>agent nodes</li><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl |
|
||||
| TCP | 6443 | K3s server nodes | Kubernetes API
|
||||
| UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN.
|
||||
| TCP | 10250 | K3s server and agent nodes | kubelet
|
||||
|
||||
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
|
||||
|
||||
| Protocol | Port | Destination | Description |
|
||||
| -------- | ---- | -------------------------------------------------------- | --------------------------------------------- |
|
||||
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
|
||||
| TCP | 443 | git.rancher.io | Rancher catalog |
|
||||
| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine |
|
||||
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
|
||||
|
||||
</details>
|
||||
|
||||
### Ports for Rancher Server Nodes on RKE
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
Typically Rancher is installed on three RKE nodes that all have the etcd, control plane and worker roles.
|
||||
|
||||
The following tables break down the port requirements for traffic between the Rancher nodes:
|
||||
|
||||
<figcaption>Rules for traffic between Rancher nodes</figcaption>
|
||||
|
||||
| Protocol | Port | Description |
|
||||
|-----|-----|----------------|
|
||||
| TCP | 443 | Rancher agents |
|
||||
| TCP | 2379 | etcd client requests |
|
||||
| TCP | 2380 | etcd peer communication |
|
||||
| TCP | 6443 | Kubernetes apiserver |
|
||||
| UDP | 8472 | Canal/Flannel VXLAN overlay networking |
|
||||
| TCP | 9099 | Canal/Flannel livenessProbe/readinessProbe |
|
||||
| TCP | 10250 | kubelet |
|
||||
| TCP | 10254 | Ingress controller livenessProbe/readinessProbe |
|
||||
|
||||
The following tables break down the port requirements for inbound and outbound traffic:
|
||||
|
||||
<figcaption>Inbound Rules for Rancher Nodes</figcaption>
|
||||
|
||||
| Protocol | Port | Source | Description |
|
||||
|-----|-----|----------------|---|
|
||||
| TCP | 22 | RKE CLI | SSH provisioning of node by RKE |
|
||||
| TCP | 80 | Load Balancer/Reverse Proxy | HTTP traffic to Rancher UI/API |
|
||||
| TCP | 443 | <ul><li>Load Balancer/Reverse Proxy</li><li>IPs of all cluster nodes and other API/UI clients</li></ul> | HTTPS traffic to Rancher UI/API |
|
||||
| TCP | 6443 | Kubernetes API clients | HTTPS traffic to Kubernetes API |
|
||||
|
||||
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
|
||||
|
||||
| Protocol | Port | Destination | Description |
|
||||
|-----|-----|----------------|---|
|
||||
| TCP | 443 | `35.160.43.145`,`35.167.242.46`,`52.33.59.17` | Rancher catalog (git.rancher.io) |
|
||||
| TCP | 22 | Any node created using a node driver | SSH provisioning of node by node driver |
|
||||
| TCP | 2376 | Any node created using a node driver | Docker daemon TLS port used by node driver |
|
||||
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
|
||||
| TCP | Provider dependent | Port of the Kubernetes API endpoint in hosted cluster | Kubernetes API |
|
||||
|
||||
</details>
|
||||
|
||||
### Ports for Rancher Server in Docker
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic:
|
||||
|
||||
<figcaption>Inbound Rules for Rancher Node</figcaption>
|
||||
|
||||
| Protocol | Port | Source | Description
|
||||
|-----|-----|----------------|---|
|
||||
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used
|
||||
| TCP | 443 | <ul><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl
|
||||
|
||||
<figcaption>Outbound Rules for Rancher Node</figcaption>
|
||||
|
||||
| Protocol | Port | Source | Description |
|
||||
|-----|-----|----------------|---|
|
||||
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
|
||||
| TCP | 443 | git.rancher.io | Rancher catalog |
|
||||
| TCP | 2376 | Any node IP from a node created using a node driver | Docker daemon TLS port used by Docker Machine |
|
||||
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
|
||||
|
||||
</details>
|
||||
|
||||
## Downstream Kubernetes Cluster Nodes
|
||||
|
||||
Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.
|
||||
|
||||
The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different [cluster types](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
The following diagram depicts the ports that are opened for each [cluster type](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md).
|
||||
|
||||
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
|
||||
|
||||
|
||||
|
||||
>**Tip:**
|
||||
>
|
||||
>If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in [Commonly Used Ports](#commonly-used-ports) as your port reference instead of the comprehensive tables below.
|
||||
|
||||
### Ports for Rancher Launched Kubernetes Clusters using Node Pools
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with nodes created in an [Infrastructure Provider](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md).
|
||||
|
||||
>**Note:**
|
||||
>The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.
|
||||
|
||||
<PortsIaasNodes/>
|
||||
|
||||
</details>
|
||||
|
||||
### Ports for Rancher Launched Kubernetes Clusters using Custom Nodes
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [Rancher Launched Kubernetes](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md) with [Custom Nodes](../../../reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/use-existing-nodes.md).
|
||||
|
||||
<PortsCustomNodes/>
|
||||
|
||||
</details>
|
||||
|
||||
### Ports for Hosted Kubernetes Clusters
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [hosted clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md).
|
||||
|
||||
<PortsImportedHosted/>
|
||||
|
||||
</details>
|
||||
|
||||
### Ports for Imported Clusters
|
||||
|
||||
|
||||
<details>
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
The following table depicts the port requirements for [imported clusters](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.md).
|
||||
|
||||
<PortsImportedHosted/>
|
||||
|
||||
</details>
|
||||
|
||||
## Other Port Considerations
|
||||
|
||||
### Commonly Used Ports
|
||||
|
||||
These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.
|
||||
|
||||
import CommonPortsTable from '../../../shared-files/_common-ports-table.md';
|
||||
|
||||
<CommonPortsTable />
|
||||
|
||||
----
|
||||
|
||||
### Local Node Traffic
|
||||
|
||||
Ports marked as `local traffic` (i.e., `9099 TCP`) in the above requirements are used for Kubernetes healthchecks (`livenessProbe` and`readinessProbe`).
|
||||
These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.
|
||||
|
||||
However, this traffic may be blocked when:
|
||||
|
||||
- You have applied strict host firewall policies on the node.
|
||||
- You are using nodes that have multiple interfaces (multihomed).
|
||||
|
||||
In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances.
|
||||
|
||||
### Rancher AWS EC2 Security Group
|
||||
|
||||
When using the [AWS EC2 node driver](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group.
|
||||
|
||||
| Type | Protocol | Port Range | Source/Destination | Rule Type |
|
||||
|-----------------|:--------:|:-----------:|------------------------|:---------:|
|
||||
| SSH | TCP | 22 | 0.0.0.0/0 | Inbound |
|
||||
| HTTP | TCP | 80 | 0.0.0.0/0 | Inbound |
|
||||
| Custom TCP Rule | TCP | 443 | 0.0.0.0/0 | Inbound |
|
||||
| Custom TCP Rule | TCP | 2376 | 0.0.0.0/0 | Inbound |
|
||||
| Custom TCP Rule | TCP | 2379-2380 | sg-xxx (rancher-nodes) | Inbound |
|
||||
| Custom UDP Rule | UDP | 4789 | sg-xxx (rancher-nodes) | Inbound |
|
||||
| Custom TCP Rule | TCP | 6443 | 0.0.0.0/0 | Inbound |
|
||||
| Custom UDP Rule | UDP | 8472 | sg-xxx (rancher-nodes) | Inbound |
|
||||
| Custom TCP Rule | TCP | 10250-10252 | sg-xxx (rancher-nodes) | Inbound |
|
||||
| Custom TCP Rule | TCP | 10256 | sg-xxx (rancher-nodes) | Inbound |
|
||||
| Custom TCP Rule | TCP | 30000-32767 | 0.0.0.0/0 | Inbound |
|
||||
| Custom UDP Rule | UDP | 30000-32767 | 0.0.0.0/0 | Inbound |
|
||||
| All traffic | All | All | 0.0.0.0/0 | Outbound |
|
||||
|
||||
### Opening SUSE Linux Ports
|
||||
|
||||
SUSE Linux may have a firewall that blocks all ports by default. To open the ports needed for adding the host to a custom cluster,
|
||||
|
||||
1. SSH into the instance.
|
||||
1. Edit /`etc/sysconfig/SuSEfirewall2` and open the required ports. In this example, ports 9796 and 10250 are also opened for monitoring:
|
||||
```
|
||||
FW_SERVICES_EXT_TCP="22 80 443 2376 2379 2380 6443 9099 9796 10250 10254 30000:32767"
|
||||
FW_SERVICES_EXT_UDP="8472 30000:32767"
|
||||
FW_ROUTE=yes
|
||||
```
|
||||
1. Restart the firewall with the new ports:
|
||||
```
|
||||
SuSEfirewall2
|
||||
```
|
||||
|
||||
**Result:** The node has the open ports required to be added to a custom cluster.
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Air Gapped Helm CLI Install
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install"/>
|
||||
</head>
|
||||
|
||||
This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.
|
||||
|
||||
For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md)
|
||||
|
||||
Throughout the installation instructions, there will be _tabs_ for each installation option.
|
||||
|
||||
> **Important:** If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
1. [Set up infrastructure and private registry](infrastructure-private-registry.md)
|
||||
2. [Collect and publish images to your private registry](publish-images.md)
|
||||
3. [Set up a Kubernetes cluster (Skip this step for Docker installations)](install-kubernetes.md)
|
||||
4. [Install Rancher](install-rancher-ha.md)
|
||||
|
||||
## Upgrades
|
||||
|
||||
To upgrade Rancher with Helm CLI in an air gap environment, follow [this procedure.](../../install-upgrade-on-a-kubernetes-cluster/upgrades/upgrades.md)
|
||||
|
||||
### [Next: Prepare your Node(s)](infrastructure-private-registry.md)
|
||||
-177
@@ -1,177 +0,0 @@
|
||||
---
|
||||
title: '1. Set up Infrastructure and Private Registry'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry"/>
|
||||
</head>
|
||||
|
||||
In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private Docker registry that must be available to your Rancher node(s).
|
||||
|
||||
An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.
|
||||
|
||||
The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to [this page.](../../installation-and-upgrade.md)
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="K3s">
|
||||
|
||||
We recommend setting up the following infrastructure for a high-availability installation:
|
||||
|
||||
- **Two Linux nodes,** typically virtual machines, in the infrastructure provider of your choice.
|
||||
- **An external database** to store the cluster data. PostgreSQL, MySQL, and etcd are supported.
|
||||
- **A load balancer** to direct traffic to the two nodes.
|
||||
- **A DNS record** to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
|
||||
- **A private Docker registry** to distribute Docker images to your machines.
|
||||
|
||||
## 1. Set up Linux Nodes
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
## 2. Set up External Datastore
|
||||
|
||||
The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.
|
||||
|
||||
For a high-availability K3s installation, you will need to set up one of the following external databases:
|
||||
|
||||
* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5)
|
||||
* [MySQL](https://www.mysql.com/) (certified against version 5.7)
|
||||
* [etcd](https://etcd.io/) (certified against version 3.3.15)
|
||||
|
||||
When you install Kubernetes, you will pass in details for K3s to connect to the database.
|
||||
|
||||
For an example of one way to set up the database, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.md) for setting up a MySQL database on Amazon's RDS service.
|
||||
|
||||
For the complete list of options that are available for configuring a K3s cluster datastore, refer to the [K3s documentation.](https://rancher.com/docs/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.](../../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)
|
||||
|
||||
> **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)
|
||||
|
||||
## 5. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
In a later step, when you set up your K3s Kubernetes cluster, you will create a [private registries configuration file](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) with details from this registry.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE">
|
||||
|
||||
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.
|
||||
- **A private Docker registry** to distribute Docker images to your machines.
|
||||
|
||||
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
|
||||
|
||||
These hosts will be disconnected from the internet, but require being able to connect with your private registry.
|
||||
|
||||
Make sure that your nodes fulfill the general installation requirements for [OS, container runtime, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
## 2. Set up the Load Balancer
|
||||
|
||||
You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.
|
||||
|
||||
When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.
|
||||
|
||||
When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.
|
||||
|
||||
For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:
|
||||
|
||||
- **A layer-4 load balancer** is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
|
||||
- **A layer-7 load balancer** is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the `--set tls=external` option when installing Rancher in a later step. For more information, refer to the [Rancher Helm chart options.](../../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination)
|
||||
|
||||
For an example showing how to set up an NGINX load balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.md)
|
||||
|
||||
For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to [this page.](../../../../how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.md)
|
||||
|
||||
> **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)
|
||||
|
||||
## 4. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a secure Docker private registry. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
In a later step, when you set up your RKE Kubernetes cluster, you will create a [private registries configuration file](https://rancher.com/docs/rke/latest/en/config-options/private-registries/) with details from this registry.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry)
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker">
|
||||
|
||||
> The Docker installation is for Rancher users that are wanting to test out Rancher. Since there is only one node and a single Docker container, if the node goes down, you will lose all the data of your Rancher server.
|
||||
>
|
||||
> For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
|
||||
## 1. Set up a Linux Node
|
||||
|
||||
This host will be disconnected from the Internet, but needs to be able to connect to your private registry.
|
||||
|
||||
Make sure that your node fulfills the general installation requirements for [OS, Docker, hardware, and networking.](../../installation-requirements/installation-requirements.md)
|
||||
|
||||
For an example of one way to set up Linux nodes, refer to this [tutorial](../../../../how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.md) for setting up nodes as instances in Amazon EC2.
|
||||
|
||||
## 2. Set up a Private Docker Registry
|
||||
|
||||
Rancher supports air gap installs using a Docker private registry on your bastion server. You must have your own private registry or other means of distributing Docker images to your machines.
|
||||
|
||||
If you need help with creating a private registry, please refer to the [official Docker documentation.](https://docs.docker.com/registry/)
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## [Next: Collect and Publish Images to your Private Registry](publish-images.md)
|
||||
-230
@@ -1,230 +0,0 @@
|
||||
---
|
||||
title: '3. Install Kubernetes (Skip for Docker Installs)'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes"/>
|
||||
</head>
|
||||
|
||||
> Skip this section if you are installing Rancher on a single node with Docker.
|
||||
|
||||
This section describes how to install a Kubernetes cluster according to our [best practices for the Rancher server environment.](../../../../reference-guides/rancher-manager-architecture/architecture-recommendations.md#environment-for-kubernetes-installations) This cluster should be dedicated to run only the Rancher server.
|
||||
|
||||
For Rancher before v2.4, Rancher should be installed on an [RKE](https://rancher.com/docs/rke/latest/en/) (Rancher Kubernetes Engine) Kubernetes cluster. RKE is a CNCF-certified Kubernetes distribution that runs entirely within Docker containers.
|
||||
|
||||
In Rancher v2.4, the Rancher management server can be installed on either an RKE cluster or a K3s Kubernetes cluster. K3s is also a fully certified Kubernetes distribution released by Rancher, but is newer than RKE. We recommend installing Rancher on K3s because K3s is easier to use, and more lightweight, with a binary size of less than 100 MB. The Rancher management server can only be run on a Kubernetes cluster in an infrastructure provider where Kubernetes is installed using RKE or K3s. Use of Rancher on hosted Kubernetes providers, such as EKS, is not supported. Note: After Rancher is installed on an RKE cluster, there is no migration path to a K3s setup at this time.
|
||||
|
||||
The steps to set up an air-gapped Kubernetes cluster on RKE or K3s are shown below.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="K3s">
|
||||
|
||||
In this guide, we are assuming you have created your nodes in your air gapped environment and have a secure Docker private registry on your bastion server.
|
||||
|
||||
## Installation Outline
|
||||
|
||||
1. [Prepare Images Directory](#1-prepare-images-directory)
|
||||
2. [Create Registry YAML](#2-create-registry-yaml)
|
||||
3. [Install K3s](#3-install-k3s)
|
||||
4. [Save and Start Using the kubeconfig File](#4-save-and-start-using-the-kubeconfig-file)
|
||||
|
||||
## 1. Prepare Images Directory
|
||||
|
||||
Obtain the images tar file for your architecture from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be running.
|
||||
|
||||
Place the tar file in the `images` directory before starting K3s on each node, for example:
|
||||
|
||||
```sh
|
||||
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
|
||||
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
|
||||
```
|
||||
|
||||
## 2. Create Registry YAML
|
||||
|
||||
Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry.
|
||||
|
||||
The registries.yaml file should look like this before plugging in the necessary information:
|
||||
|
||||
```
|
||||
---
|
||||
mirrors:
|
||||
customreg:
|
||||
endpoint:
|
||||
- "https://ip-to-server:5000"
|
||||
configs:
|
||||
customreg:
|
||||
auth:
|
||||
username: xxxxxx # this is the registry username
|
||||
password: xxxxxx # this is the registry password
|
||||
tls:
|
||||
cert_file: <path to the cert file used in the registry>
|
||||
key_file: <path to the key file used in the registry>
|
||||
ca_file: <path to the ca file used in the registry>
|
||||
```
|
||||
|
||||
Note, at this time only secure registries are supported with K3s (SSL with custom CA).
|
||||
|
||||
For more information on private registries configuration file for K3s, refer to the [K3s documentation.](https://rancher.com/docs/k3s/latest/en/installation/private-registry/)
|
||||
|
||||
## 3. Install K3s
|
||||
|
||||
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.
|
||||
|
||||
Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images tar.
|
||||
Also obtain the K3s install script at https://get.k3s.io
|
||||
|
||||
Place the binary in `/usr/local/bin` on each node.
|
||||
Place the install script anywhere on each node, and name it `install.sh`.
|
||||
|
||||
Install K3s on each server:
|
||||
|
||||
```
|
||||
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
|
||||
```
|
||||
|
||||
Install K3s on each agent:
|
||||
|
||||
```
|
||||
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh
|
||||
```
|
||||
|
||||
Note, take care to ensure you replace `myserver` with the IP or valid DNS of the server and replace `mynodetoken` with the node-token from the server.
|
||||
The node-token is on the server at `/var/lib/rancher/k3s/server/node-token`
|
||||
|
||||
>**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
|
||||
|
||||
## 4. Save and Start Using the kubeconfig File
|
||||
|
||||
When you installed K3s on each Rancher server node, a `kubeconfig` file was created on the node at `/etc/rancher/k3s/k3s.yaml`. This file contains credentials for full access to the cluster, and you should save this file in a secure location.
|
||||
|
||||
To use this `kubeconfig` file,
|
||||
|
||||
1. Install [kubectl,](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`:
|
||||
|
||||
```
|
||||
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](https://rancher.com/docs/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.
|
||||
|
||||
## Note on Upgrading
|
||||
|
||||
Upgrading an air-gap environment can be accomplished in the following manner:
|
||||
|
||||
1. Download the new air-gap images (tar file) from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each node. Delete the old tar file.
|
||||
2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
|
||||
3. Restart the K3s service (if not restarted automatically by installer).
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="RKE">
|
||||
|
||||
We will create a Kubernetes cluster using Rancher Kubernetes Engine (RKE). Before being able to start your Kubernetes cluster, you’ll need to install RKE and create a RKE config file.
|
||||
|
||||
## 1. Install RKE
|
||||
|
||||
Install RKE by following the instructions in the [RKE documentation.](https://rancher.com/docs/rke/latest/en/installation/)
|
||||
|
||||
## 2. Create an RKE Config File
|
||||
|
||||
From a system that can access ports 22/TCP and 6443/TCP on the Linux host node(s) that you set up in a previous step, use the sample below to create a new file named `rancher-cluster.yml`.
|
||||
|
||||
This file is an RKE configuration file, which is a configuration for the cluster you're deploying Rancher to.
|
||||
|
||||
Replace values in the code sample below with help of the _RKE Options_ table. Use the IP address or DNS names of the [3 nodes](../../advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.md) you created.
|
||||
|
||||
> **Tip:** For more details on the options available, see the RKE [Config Options](https://rancher.com/docs/rke/latest/en/config-options/).
|
||||
|
||||
<figcaption>RKE Options</figcaption>
|
||||
|
||||
| Option | Required | Description |
|
||||
| ------------------ | -------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `address` | ✓ | The DNS or IP address for the node within the air gapped network. |
|
||||
| `user` | ✓ | A user that can run Docker commands. |
|
||||
| `role` | ✓ | List of Kubernetes roles assigned to the node. |
|
||||
| `internal_address` | optional<sup>1</sup> | The DNS or IP address used for internal cluster traffic. |
|
||||
| `ssh_key_path` | | Path to the SSH private key used to authenticate to the node (defaults to `~/.ssh/id_rsa`). |
|
||||
|
||||
> <sup>1</sup> Some services like AWS EC2 require setting the `internal_address` if you want to use self-referencing security groups or firewalls.
|
||||
|
||||
```yaml
|
||||
nodes:
|
||||
- address: 10.10.3.187 # node air gap network IP
|
||||
internal_address: 172.31.7.22 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.254 # node air gap network IP
|
||||
internal_address: 172.31.13.132 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
- address: 10.10.3.89 # node air gap network IP
|
||||
internal_address: 172.31.3.216 # node intra-cluster IP
|
||||
user: rancher
|
||||
role: ['controlplane', 'etcd', 'worker']
|
||||
ssh_key_path: /home/user/.ssh/id_rsa
|
||||
|
||||
private_registries:
|
||||
- url: <REGISTRY.YOURDOMAIN.COM:PORT> # private registry url
|
||||
user: rancher
|
||||
password: '*********'
|
||||
is_default: true
|
||||
```
|
||||
|
||||
## 3. Run RKE
|
||||
|
||||
After configuring `rancher-cluster.yml`, bring up your Kubernetes cluster:
|
||||
|
||||
```
|
||||
rke up --config ./rancher-cluster.yml
|
||||
```
|
||||
|
||||
## 4. Save Your Files
|
||||
|
||||
> **Important**
|
||||
> The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.
|
||||
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `rancher-cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_rancher-cluster.yml`: The [Kubeconfig file](https://rancher.com/docs/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](https://rancher.com/docs/rke/latest/en/installation/#kubernetes-cluster-state), this file contains the current state of the cluster including the RKE configuration and the certificates.<br/><br/>_The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher._
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
> **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](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md) page.
|
||||
|
||||
## [Next: Install Rancher](install-rancher-ha.md)
|
||||
-363
@@ -1,363 +0,0 @@
|
||||
---
|
||||
title: 4. Install Rancher
|
||||
---
|
||||
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha"/>
|
||||
</head>
|
||||
|
||||
This section is about how to deploy Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are _tabs_ for either a high availability (recommended) or a Docker installation.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Kubernetes Install (Recommended)">
|
||||
|
||||
Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.
|
||||
|
||||
## 1. Add the Helm Chart Repository
|
||||
|
||||
From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.
|
||||
|
||||
1. If you haven't already, install `helm` locally on a workstation that has internet access. Note: Refer to the [Helm version requirements](../../resources/helm-version-requirements.md) to choose a version of Helm to install Rancher.
|
||||
|
||||
2. Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Rancher Version](../../resources/choose-a-rancher-version.md).
|
||||
- Latest: Recommended for trying out the newest features
|
||||
```
|
||||
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
|
||||
```
|
||||
- Stable: Recommended for production environments
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
- Alpha: Experimental preview of upcoming releases.
|
||||
```
|
||||
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
|
||||
```
|
||||
Note: Upgrades are not supported to, from, or between Alphas.
|
||||
|
||||
3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a `.tgz` file.
|
||||
```plain
|
||||
helm fetch rancher-<CHART_REPO>/rancher
|
||||
```
|
||||
|
||||
If you require a specific version of Rancher, you can fetch this with the Helm `--version` parameter like in the following example:
|
||||
```plain
|
||||
helm fetch rancher-stable/rancher --version=v2.4.8
|
||||
```
|
||||
|
||||
## 2. Choose your SSL Configuration
|
||||
|
||||
Rancher Server is designed to be secure by default and requires SSL/TLS configuration.
|
||||
|
||||
When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.
|
||||
|
||||
> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer](../../../../reference-guides/installation-references/helm-chart-options.md#external-tls-termination).
|
||||
|
||||
| Configuration | Chart option | Description | Requires cert-manager |
|
||||
| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)<br/> This is the **default** and does not need to be added when rendering the Helm template. | yes |
|
||||
| Certificates from Files | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s). <br/> This option must be passed when rendering the Rancher Helm template. | no |
|
||||
|
||||
## 3. Render the Rancher Helm Template
|
||||
|
||||
When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.
|
||||
|
||||
| Chart Option | Chart Value | Description |
|
||||
| ----------------------- | -------------------------------- | ---- |
|
||||
| `certmanager.version` | `<version>` | Configure proper Rancher TLS issuer depending of running cert-manager version. |
|
||||
| `systemDefaultRegistry` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. 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. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ |
|
||||
|
||||
Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), complete one of the procedures below.
|
||||
|
||||
### Option A: Default Self-Signed Certificate
|
||||
|
||||
<details id="k8s-1">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.
|
||||
|
||||
> **Note:**
|
||||
> Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation](../../resources/upgrade-cert-manager.md).
|
||||
|
||||
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 v1.0.4
|
||||
```
|
||||
|
||||
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.
|
||||
```plain
|
||||
helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \
|
||||
--namespace cert-manager \
|
||||
--set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
|
||||
--set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
|
||||
--set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector
|
||||
```
|
||||
|
||||
1. Download the required CRD file for cert-manager
|
||||
```plain
|
||||
curl -L -o cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
|
||||
```
|
||||
|
||||
1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
|
||||
Placeholder | Description
|
||||
------------|-------------
|
||||
`<VERSION>` | The version number of the output tarball.
|
||||
`<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
|
||||
`<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
|
||||
`<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set certmanager.version=<CERTMANAGER_VERSION> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6`
|
||||
|
||||
</details>
|
||||
|
||||
### Option B: Certificates From Files using Kubernetes Secrets
|
||||
|
||||
<details id="k8s-2">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.
|
||||
|
||||
Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------- |
|
||||
| `<VERSION>` | The version number of the output tarball. |
|
||||
| `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry. |
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`:
|
||||
|
||||
```plain
|
||||
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<RANCHER.YOURDOMAIN.COM> \
|
||||
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
|
||||
--set ingress.tls.source=secret \
|
||||
--set privateCA=true \
|
||||
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
|
||||
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
|
||||
```
|
||||
|
||||
**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6`
|
||||
|
||||
Then refer to [Adding TLS Secrets](../../resources/add-tls-secrets.md) to publish the certificate files so Rancher and the ingress controller can use them.
|
||||
|
||||
</details>
|
||||
|
||||
## 4. Install Rancher
|
||||
|
||||
Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.
|
||||
|
||||
Use `kubectl` to create namespaces and apply the rendered manifests.
|
||||
|
||||
If you choose to use self-signed certificates in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), install cert-manager.
|
||||
|
||||
### For Self-Signed Certificate Installs, Install cert-manager
|
||||
|
||||
<details id="install-cert-manager">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
If you are using self-signed certificates, install cert-manager:
|
||||
|
||||
1. Create the namespace for cert-manager.
|
||||
```plain
|
||||
kubectl create namespace cert-manager
|
||||
```
|
||||
|
||||
1. Create the cert-manager CustomResourceDefinitions (CRDs).
|
||||
```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, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
|
||||
|
||||
1. Launch cert-manager.
|
||||
```plain
|
||||
kubectl apply -R -f ./cert-manager
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Install Rancher with kubectl
|
||||
|
||||
```plain
|
||||
kubectl create namespace cattle-system
|
||||
kubectl -n cattle-system apply -R -f ./rancher
|
||||
```
|
||||
**Step Result:** If you are installing Rancher v2.3.0+, the installation is complete.
|
||||
|
||||
> **Note:** If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.
|
||||
|
||||
## 5. For Rancher Versions Before v2.3.0, Configure System Charts
|
||||
|
||||
If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in GitHub, an air gapped installation will not be able to access these charts. Therefore, you must [configure the Rancher system charts](../../resources/local-system-charts.md).
|
||||
|
||||
## Additional Resources
|
||||
|
||||
These resources could be helpful when installing Rancher:
|
||||
|
||||
- [Rancher Helm chart options](../../../../reference-guides/installation-references/helm-chart-options.md)
|
||||
- [Adding TLS secrets](../../resources/add-tls-secrets.md)
|
||||
- [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Docker Install">
|
||||
|
||||
The Docker installation is for Rancher users who want to test out Rancher.
|
||||
|
||||
Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
> **Important:** There is no upgrade path to transition your Docker installation to a Kubernetes Installation.** Instead of running the single node installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.
|
||||
|
||||
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
|
||||
|
||||
| Environment Variable Key | Environment Variable Value | Description |
|
||||
| -------------------------------- | -------------------------------- | ---- |
|
||||
| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `<REGISTRY.YOURDOMAIN.COM:PORT>` | Configure Rancher server to always pull from your private registry when provisioning clusters. |
|
||||
| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. 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. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. _Available as of v2.3.0_ |
|
||||
|
||||
> **Do you want to...**
|
||||
>
|
||||
> - Configure custom CA root certificate to access your services? See [Custom CA root certificate](../../resources/custom-ca-root-certificates.md).
|
||||
> - Record all transactions with the Rancher API? See [API Auditing](../../../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log).
|
||||
|
||||
- For Rancher before v2.3.0, you will need to mirror the `system-charts` repository to a location in your network that Rancher can reach. Then, after Rancher is installed, you will need to configure Rancher to use that repository. For details, refer to the documentation on [setting up the system charts for Rancher before v2.3.0.](../../resources/local-system-charts.md)
|
||||
|
||||
Choose from the following options:
|
||||
|
||||
### Option A: Default Self-Signed Certificate
|
||||
|
||||
<details id="option-a">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.
|
||||
|
||||
Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../../reference-guides/installation-references/helm-chart-options.md) that you want to install. |
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option B: Bring Your Own Certificate: Self-Signed
|
||||
|
||||
<details id="option-b">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.
|
||||
|
||||
> **Prerequisites:**
|
||||
> From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice.
|
||||
>
|
||||
> - The certificate files must be in PEM format.
|
||||
> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.](../rancher-on-a-single-node-with-docker/certificate-troubleshooting.md)
|
||||
|
||||
After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
| `<CA_CERTS.pem>` | The path to the certificate authority's certificate. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../../reference-guides/installation-references/helm-chart-options.md) that you want to install. |
|
||||
|
||||
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Option C: Bring Your Own Certificate: Signed by Recognized CA
|
||||
|
||||
<details id="option-c">
|
||||
<summary>Click to expand</summary>
|
||||
|
||||
In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.
|
||||
|
||||
> **Prerequisite:** The certificate files must be in PEM format.
|
||||
|
||||
After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
|
||||
|
||||
| Placeholder | Description |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `<CERT_DIRECTORY>` | The path to the directory containing your certificate files. |
|
||||
| `<FULL_CHAIN.pem>` | The path to your full certificate chain. |
|
||||
| `<PRIVATE_KEY.pem>` | The path to the private key for your certificate. |
|
||||
| `<REGISTRY.YOURDOMAIN.COM:PORT>` | Your private registry URL and port. |
|
||||
| `<RANCHER_VERSION_TAG>` | The release tag of the [Rancher version](../../../../reference-guides/installation-references/helm-chart-options.md) that you want to install. |
|
||||
|
||||
> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher.
|
||||
|
||||
```
|
||||
docker run -d --restart=unless-stopped \
|
||||
-p 80:80 -p 443:443 \
|
||||
--no-cacerts \
|
||||
-v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
|
||||
-v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
|
||||
-e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
|
||||
-e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
|
||||
<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
If you are installing Rancher v2.3.0+, the installation is complete.
|
||||
|
||||
> **Note:** If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/telemetry.md) during the initial login.
|
||||
|
||||
If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in GitHub, an air gapped installation will not be able to access these charts. Therefore, you must [configure the Rancher system charts](../../resources/local-system-charts.md).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Other Installation Methods
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/pages-for-subheaders/other-installation-methods"/>
|
||||
</head>
|
||||
|
||||
### Air Gapped Installations
|
||||
|
||||
Follow [these steps](air-gapped-helm-cli-install.md) to install the Rancher server in an air gapped environment.
|
||||
|
||||
An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
|
||||
|
||||
### Docker Installations
|
||||
|
||||
The [single-node Docker installation](../rancher-on-a-single-node-with-docker/rancher-on-a-single-node-with-docker.md) is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a `docker run` command.
|
||||
|
||||
The Docker installation is for development and testing environments only.
|
||||
|
||||
Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.
|
||||
|
||||
There is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.
|
||||
-296
@@ -1,296 +0,0 @@
|
||||
---
|
||||
title: '2. Collect and Publish Images to your Private Registry'
|
||||
---
|
||||
|
||||
<head>
|
||||
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images"/>
|
||||
</head>
|
||||
|
||||
This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.
|
||||
|
||||
By default, all images used to [provision Kubernetes clusters](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/kubernetes-clusters-in-rancher-setup.md) or launch any [tools](../../../../reference-guides/rancher-cluster-tools.md) in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.
|
||||
|
||||
Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.
|
||||
|
||||
The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any [downstream Kubernetes clusters using Windows nodes](../../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/use-windows-clusters.md), there are separate instructions to support the images needed.
|
||||
|
||||
> **Prerequisites:**
|
||||
>
|
||||
> You must have a [private registry](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry) available to use.
|
||||
>
|
||||
> If the registry has certs, follow [this K3s documentation](https://rancher.com/docs/k3s/latest/en/installation/private-registry/) about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="Linux Only Clusters">
|
||||
|
||||
For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.
|
||||
|
||||
1. [Find the required assets for your Rancher version](#1-find-the-required-assets-for-your-rancher-version)
|
||||
2. [Collect the cert-manager image](#2-collect-the-cert-manager-image) (unless you are bringing your own certificates or terminating TLS on a load balancer)
|
||||
3. [Save the images to your workstation](#3-save-the-images-to-your-workstation)
|
||||
4. [Populate the private registry](#4-populate-the-private-registry)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Go to our [releases page,](https://github.com/rancher/rancher/releases) find the Rancher v2.x.x release that you want to install, and click **Assets.** Note: Don't use releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's **Assets** section, download the following files, which are required to install Rancher in an air gap environment:
|
||||
|
||||
| Release File | Description |
|
||||
| ---------------- | -------------- |
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
### 2. Collect the cert-manager image
|
||||
|
||||
> Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.
|
||||
|
||||
In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../resources/upgrade-cert-manager.md).
|
||||
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v1.0.4
|
||||
helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
### 3. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Next, you will move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
The `rancher-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push `rancher-images.txt` and `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Linux and Windows Clusters">
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
For Rancher servers that will provision Linux and Windows clusters, there are distinctive steps to populate your private registry for the Windows images and the Linux images. Since a Windows cluster is a mix of Linux and Windows nodes, the Linux images pushed into the private registry are manifests.
|
||||
|
||||
## Windows Steps
|
||||
|
||||
The Windows images need to be collected and pushed from a Windows server workstation.
|
||||
|
||||
1. <a href="#windows-1">Find the required assets for your Rancher version</a>
|
||||
2. <a href="#windows-2">Save the images to your Windows Server workstation</a>
|
||||
3. <a href="#windows-3">Prepare the Docker daemon</a>
|
||||
4. <a href="#windows-4">Populate the private registry</a>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
These steps expect you to use a Windows Server 1809 workstation that has internet access, access to your private registry, and at least 50 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
Your registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.
|
||||
|
||||
<a name="windows-1"></a>
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments.
|
||||
|
||||
2. From the release's "Assets" section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
|----------------------------|------------------|
|
||||
| `rancher-windows-images.txt` | This file contains a list of Windows images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.ps1` | This script pulls all the images in the `rancher-windows-images.txt` from Docker Hub and saves all of the images as `rancher-windows-images.tar.gz`. |
|
||||
| `rancher-load-images.ps1` | This script loads the images from the `rancher-windows-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
<a name="windows-2"></a>
|
||||
|
||||
### 2. Save the images to your Windows Server workstation
|
||||
|
||||
1. Using `powershell`, go to the directory that has the files that were downloaded in the previous step.
|
||||
|
||||
1. Run `rancher-save-images.ps1` to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.ps1
|
||||
```
|
||||
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
<a name="windows-3"></a>
|
||||
|
||||
### 3. Prepare the Docker daemon
|
||||
|
||||
Append your private registry address to the `allow-nondistributable-artifacts` config field in the Docker daemon (`C:\ProgramData\Docker\config\daemon.json`). Since the base image of Windows images are maintained by the `mcr.microsoft.com` registry, this step is required as the layers in the Microsoft registry are missing from Docker Hub and need to be pulled into the private registry.
|
||||
|
||||
```
|
||||
{
|
||||
...
|
||||
"allow-nondistributable-artifacts": [
|
||||
...
|
||||
"<REGISTRY.YOURDOMAIN.COM:PORT>"
|
||||
]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
<a name="windows-4"></a>
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-windows-images.tar.gz` to your private registry using the scripts to load the images.
|
||||
|
||||
The `rancher-windows-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.ps1` script. The `rancher-windows-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Using `powershell`, log into your private registry if required:
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Using `powershell`, use `rancher-load-images.ps1` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
```plain
|
||||
./rancher-load-images.ps1 --registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
## Linux Steps
|
||||
|
||||
The Linux images needs to be collected and pushed from a Linux host, but _must be done after_ populating the Windows images into the private registry. These step are different from the Linux only steps as the Linux images that are pushed will actually manifests that support Windows and Linux images.
|
||||
|
||||
1. <a href="#linux-1">Find the required assets for your Rancher version</a>
|
||||
2. <a href="#linux-2">Collect all the required images</a>
|
||||
3. <a href="#linux-3">Save the images to your Linux workstation</a>
|
||||
4. <a href="#linux-4">Populate the private registry</a>
|
||||
|
||||
### Prerequisites
|
||||
|
||||
You must populate the private registry with the Windows images before populating the private registry with Linux images. If you have already populated the registry with Linux images, you will need to follow these instructions again as they will publish manifests that support Windows and Linux images.
|
||||
|
||||
These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.
|
||||
|
||||
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
|
||||
|
||||
<a name="linux-1"></a>
|
||||
|
||||
### 1. Find the required assets for your Rancher version
|
||||
|
||||
1. Browse to our [releases page](https://github.com/rancher/rancher/releases) and find the Rancher v2.x.x release that you want to install. Don't download releases marked `rc` or `Pre-release`, as they are not stable for production environments. Click **Assets.**
|
||||
|
||||
2. From the release's **Assets** section, download the following files:
|
||||
|
||||
| Release File | Description |
|
||||
|----------------------------| -------------------------- |
|
||||
| `rancher-images.txt` | This file contains a list of images needed to install Rancher, provision clusters and user Rancher tools. |
|
||||
| `rancher-windows-images.txt` | This file contains a list of images needed to provision Windows clusters. |
|
||||
| `rancher-save-images.sh` | This script pulls all the images in the `rancher-images.txt` from Docker Hub and saves all of the images as `rancher-images.tar.gz`. |
|
||||
| `rancher-load-images.sh` | This script loads images from the `rancher-images.tar.gz` file and pushes them to your private registry. |
|
||||
|
||||
<a name="linux-2"></a>
|
||||
|
||||
### 2. Collect all the required images
|
||||
|
||||
**For Kubernetes Installs using Rancher Generated Self-Signed Certificate:** In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the [`cert-manager`](https://hub.helm.sh/charts/jetstack/cert-manager) image to `rancher-images.txt` as well. You skip this step if you are using you using your own certificates.
|
||||
|
||||
1. Fetch the latest `cert-manager` Helm chart and parse the template for image details:
|
||||
> **Note:** Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our [upgrade documentation](../../resources/upgrade-cert-manager.md).
|
||||
```plain
|
||||
helm repo add jetstack https://charts.jetstack.io
|
||||
helm repo update
|
||||
helm fetch jetstack/cert-manager --version v0.12.0
|
||||
helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt
|
||||
```
|
||||
|
||||
2. Sort and unique the images list to remove any overlap between the sources:
|
||||
```plain
|
||||
sort -u rancher-images.txt -o rancher-images.txt
|
||||
```
|
||||
|
||||
<a name="linux-3"></a>
|
||||
|
||||
### 3. Save the images to your workstation
|
||||
|
||||
1. Make `rancher-save-images.sh` an executable:
|
||||
```
|
||||
chmod +x rancher-save-images.sh
|
||||
```
|
||||
|
||||
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
|
||||
```plain
|
||||
./rancher-save-images.sh --image-list ./rancher-images.txt
|
||||
```
|
||||
|
||||
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
|
||||
|
||||
<a name="linux-4"></a>
|
||||
|
||||
### 4. Populate the private registry
|
||||
|
||||
Move the images in the `rancher-images.tar.gz` to your private registry using the `rancher-load-images.sh script` to load the images.
|
||||
|
||||
The image list, `rancher-images.txt` or `rancher-windows-images.txt`, is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script. The `rancher-images.tar.gz` should also be in the same directory.
|
||||
|
||||
1. Log into your private registry if required:
|
||||
|
||||
```plain
|
||||
docker login <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
1. Make `rancher-load-images.sh` an executable:
|
||||
|
||||
```
|
||||
chmod +x rancher-load-images.sh
|
||||
```
|
||||
|
||||
1. Use `rancher-load-images.sh` to extract, tag and push the images from `rancher-images.tar.gz` to your private registry:
|
||||
|
||||
```plain
|
||||
./rancher-load-images.sh --image-list ./rancher-images.txt \
|
||||
--windows-image-list ./rancher-windows-images.txt \
|
||||
--registry <REGISTRY.YOURDOMAIN.COM:PORT>
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### [Next step for Kubernetes Installs - Launch a Kubernetes Cluster](install-kubernetes.md)
|
||||
|
||||
### [Next step for Docker Installs - Install Rancher](install-rancher-ha.md)
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user