From 2b7dd2867f95fb1bd03ba62900747c187d55db68 Mon Sep 17 00:00:00 2001 From: Denise Schannon Date: Fri, 22 Mar 2019 11:55:01 -0700 Subject: [PATCH] navigation reorg --- .../rancher/v2.x/en/admin-settings/_index.md | 16 +- .../admin-settings/authentication/_index.md | 4 +- .../drivers/_index.md | 2 +- .../drivers/cluster-drivers/_index.md | 0 .../drivers/node-drivers/_index.md | 0 .../globaldns/_index.md | 2 +- .../v2.x/en/admin-settings/log-in/_index.md | 4 +- .../v2.x/en/admin-settings/rbac/_index.md | 4 +- .../admin-settings/removing-rancher/_index.md | 16 - content/rancher/v2.x/en/cli/_index.md | 4 +- .../rancher/v2.x/en/cluster-admin/_index.md | 70 ++ .../backing-up-etcd}/_index.md | 22 +- .../certificate-rotation/_index.md | 2 +- .../cleaning-cluster-nodes}/_index.md | 27 +- .../cloning-clusters/_index.md | 4 +- .../cluster-members/_index.md | 2 +- .../editing-clusters/_index.md | 13 +- .../kubeconfig/_index.md | 5 +- .../kubectl/_index.md | 3 +- .../nodes/_index.md | 22 +- .../projects-and-namespaces/_index.md | 92 +- .../cluster-admin/recovering-etcd/_index.md | 64 ++ .../en/{ => cluster-admin}/tools/_index.md | 58 +- .../en/cluster-admin/tools/alerts/_index.md | 214 +++++ .../tools/logging/_index.md | 13 +- .../tools/logging/custom/_index.md | 90 ++ .../tools/logging/elasticsearch/_index.md | 73 ++ .../tools/logging/fluentd/_index.md | 68 ++ .../tools/logging/kafka/_index.md | 75 ++ .../tools/logging/splunk/_index.md | 13 +- .../tools/logging/syslog/_index.md | 74 ++ .../tools/monitoring/_index.md | 14 +- .../tools/monitoring/expression/_index.md | 0 .../cluster-admin/tools/notifiers/_index.md | 95 ++ .../volumes-and-storage/_index.md | 5 +- .../volumes-and-storage/examples/_index.md | 1 + .../examples/nfs/_index.md | 1 + .../examples/vsphere/_index.md | 5 +- .../persistent-volume-claims/_index.md | 1 + .../custom-clusters}/agent-options/_index.md | 3 + .../hosted-kubernetes-clusters/_index.md | 2 +- .../hosted-kubernetes-clusters/ack/_index.md | 2 +- .../hosted-kubernetes-clusters/cce/_index.md | 2 +- .../hosted-kubernetes-clusters/tke/_index.md | 4 +- .../cluster-provisioning/production/_index.md | 2 +- .../rke-clusters/node-pools/_index.md | 2 +- .../install-rancher/_index.md | 4 +- .../en/installation/arm64-platform/_index.md | 27 - .../ha/helm-rancher/chart-options/_index.md | 2 +- .../v2.x/en/installation/options/_index.md | 12 + .../options}/api-audit-log/_index.md | 11 +- .../custom-ca-root-certificate/_index.md | 20 +- .../options}/tls-settings/_index.md | 8 +- .../en/installation/server-tags/_index.md | 4 +- .../en/installation/single-node/_index.md | 38 +- .../single-node-install-external-lb/_index.md | 85 +- .../rancher/v2.x/en/k8s-in-rancher/_index.md | 2 +- .../horitzontal-pod-autoscaler/_index.md | 29 +- .../en/k8s-in-rancher/pipelines/_index.md | 869 ++++++++++++++++++ .../k8s-in-rancher/recovering-etcd/_index.md | 34 - .../rancher/v2.x/en/project-admin/_index.md | 33 + .../editing-projects/_index.md | 19 +- .../en/project-admin/namespaces/_index.md | 80 ++ .../project-members/_index.md | 3 +- .../resource-quotas/_index.md | 27 +- .../v2.x/en/project-admin/tools/_index.md | 76 ++ .../en/project-admin/tools/alerts/_index.md | 163 ++++ .../en/project-admin/tools/logging/_index.md | 57 ++ .../tools/logging/custom/_index.md | 0 .../tools/logging/elasticsearch/_index.md | 0 .../tools/logging/fluentd/_index.md | 0 .../tools/logging/kafka/_index.md | 0 .../tools/logging/splunk/_index.md | 102 ++ .../tools/logging/syslog/_index.md | 0 .../project-admin/tools/monitoring/_index.md | 308 +++++++ .../tools/monitoring/expression/_index.md | 379 ++++++++ .../tools/pipelines/_index.md | 3 +- .../tools/pipelines/concepts/_index.md | 4 +- .../tools/pipelines/configurations/_index.md | 21 +- .../tools/pipelines/docs-for-v2.0.x/_index.md | 2 + .../pipelines/quick-start-guide/_index.md | 8 +- .../tools/pipelines/reference/_index.md | 2 + .../_index.md | 16 +- content/rancher/v2.x/en/security/_index.md | 2 +- .../en/tools/notifiers-and-alerts/_index.md | 455 --------- .../rancher/v2.x/en/v1.6-migration/_index.md | 8 +- 86 files changed, 3251 insertions(+), 857 deletions(-) rename content/rancher/v2.x/en/{tools => admin-settings}/drivers/_index.md (99%) rename content/rancher/v2.x/en/{tools => admin-settings}/drivers/cluster-drivers/_index.md (100%) rename content/rancher/v2.x/en/{tools => admin-settings}/drivers/node-drivers/_index.md (100%) rename content/rancher/v2.x/en/{tools => admin-settings}/globaldns/_index.md (99%) delete mode 100644 content/rancher/v2.x/en/admin-settings/removing-rancher/_index.md create mode 100644 content/rancher/v2.x/en/cluster-admin/_index.md rename content/rancher/v2.x/en/{tools/snapshots => cluster-admin/backing-up-etcd}/_index.md (77%) rename content/rancher/v2.x/en/{cluster-provisioning/rke-clusters => cluster-admin}/certificate-rotation/_index.md (99%) rename content/rancher/v2.x/en/{admin-settings/removing-rancher/user-cluster-nodes => cluster-admin/cleaning-cluster-nodes}/_index.md (92%) rename content/rancher/v2.x/en/{cluster-provisioning => cluster-admin}/cloning-clusters/_index.md (98%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/cluster-members/_index.md (98%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/editing-clusters/_index.md (98%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/kubeconfig/_index.md (97%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/kubectl/_index.md (98%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/nodes/_index.md (98%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/projects-and-namespaces/_index.md (69%) create mode 100644 content/rancher/v2.x/en/cluster-admin/recovering-etcd/_index.md rename content/rancher/v2.x/en/{ => cluster-admin}/tools/_index.md (60%) create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/alerts/_index.md rename content/rancher/v2.x/en/{ => cluster-admin}/tools/logging/_index.md (94%) create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/logging/custom/_index.md create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/logging/elasticsearch/_index.md create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/logging/fluentd/_index.md create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/logging/kafka/_index.md rename content/rancher/v2.x/en/{ => cluster-admin}/tools/logging/splunk/_index.md (96%) mode change 100755 => 100644 create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/logging/syslog/_index.md rename content/rancher/v2.x/en/{ => cluster-admin}/tools/monitoring/_index.md (99%) rename content/rancher/v2.x/en/{ => cluster-admin}/tools/monitoring/expression/_index.md (100%) create mode 100644 content/rancher/v2.x/en/cluster-admin/tools/notifiers/_index.md rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/volumes-and-storage/_index.md (99%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/volumes-and-storage/examples/_index.md (91%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/volumes-and-storage/examples/nfs/_index.md (97%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/volumes-and-storage/examples/vsphere/_index.md (97%) rename content/rancher/v2.x/en/{k8s-in-rancher => cluster-admin}/volumes-and-storage/persistent-volume-claims/_index.md (96%) rename content/rancher/v2.x/en/{admin-settings => cluster-provisioning/custom-clusters}/agent-options/_index.md (98%) delete mode 100644 content/rancher/v2.x/en/installation/arm64-platform/_index.md create mode 100644 content/rancher/v2.x/en/installation/options/_index.md rename content/rancher/v2.x/en/{admin-settings => installation/options}/api-audit-log/_index.md (98%) rename content/rancher/v2.x/en/{admin-settings => installation/options}/custom-ca-root-certificate/_index.md (52%) rename content/rancher/v2.x/en/{admin-settings => installation/options}/tls-settings/_index.md (88%) create mode 100644 content/rancher/v2.x/en/k8s-in-rancher/pipelines/_index.md delete mode 100644 content/rancher/v2.x/en/k8s-in-rancher/recovering-etcd/_index.md create mode 100644 content/rancher/v2.x/en/project-admin/_index.md rename content/rancher/v2.x/en/{k8s-in-rancher/projects-and-namespaces => project-admin}/editing-projects/_index.md (98%) create mode 100644 content/rancher/v2.x/en/project-admin/namespaces/_index.md rename content/rancher/v2.x/en/{k8s-in-rancher/projects-and-namespaces => project-admin}/project-members/_index.md (90%) rename content/rancher/v2.x/en/{k8s-in-rancher/projects-and-namespaces => project-admin}/resource-quotas/_index.md (94%) create mode 100644 content/rancher/v2.x/en/project-admin/tools/_index.md create mode 100644 content/rancher/v2.x/en/project-admin/tools/alerts/_index.md create mode 100644 content/rancher/v2.x/en/project-admin/tools/logging/_index.md rename content/rancher/v2.x/en/{ => project-admin}/tools/logging/custom/_index.md (100%) rename content/rancher/v2.x/en/{ => project-admin}/tools/logging/elasticsearch/_index.md (100%) rename content/rancher/v2.x/en/{ => project-admin}/tools/logging/fluentd/_index.md (100%) mode change 100755 => 100644 rename content/rancher/v2.x/en/{ => project-admin}/tools/logging/kafka/_index.md (100%) create mode 100644 content/rancher/v2.x/en/project-admin/tools/logging/splunk/_index.md rename content/rancher/v2.x/en/{ => project-admin}/tools/logging/syslog/_index.md (100%) create mode 100644 content/rancher/v2.x/en/project-admin/tools/monitoring/_index.md create mode 100644 content/rancher/v2.x/en/project-admin/tools/monitoring/expression/_index.md rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/_index.md (98%) rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/concepts/_index.md (96%) rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/configurations/_index.md (98%) rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/docs-for-v2.0.x/_index.md (98%) rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/quick-start-guide/_index.md (93%) rename content/rancher/v2.x/en/{ => project-admin}/tools/pipelines/reference/_index.md (97%) rename content/rancher/v2.x/en/{admin-settings/removing-rancher/rancher-cluster-nodes => removing-rancher}/_index.md (78%) delete mode 100644 content/rancher/v2.x/en/tools/notifiers-and-alerts/_index.md diff --git a/content/rancher/v2.x/en/admin-settings/_index.md b/content/rancher/v2.x/en/admin-settings/_index.md index 2ec2b76e42e..b586648bd6f 100644 --- a/content/rancher/v2.x/en/admin-settings/_index.md +++ b/content/rancher/v2.x/en/admin-settings/_index.md @@ -1,5 +1,5 @@ --- -title: Administration +title: Global Configuration weight: 1100 aliases: - /rancher/v2.x/en/concepts/global-configuration/ @@ -7,3 +7,17 @@ aliases: --- After installation, the system administrator should configure Rancher to configure security, default settings, and user access. + +## Drivers + +Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes. + +For more information, see [Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/). + +## Global DNS + +_Available as v2.2.0_ + +When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS. + +For more information on how to use this feature, see [Global DNS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/globaldns/). diff --git a/content/rancher/v2.x/en/admin-settings/authentication/_index.md b/content/rancher/v2.x/en/admin-settings/authentication/_index.md index 31ea97a8d8e..dab199ab64a 100644 --- a/content/rancher/v2.x/en/admin-settings/authentication/_index.md +++ b/content/rancher/v2.x/en/admin-settings/authentication/_index.md @@ -1,6 +1,6 @@ --- title: Authentication -weight: 1110 +weight: 1115 aliases: - /rancher/v2.x/en/concepts/global-configuration/authentication/ - /rancher/v2.x/en/tasks/global-configuration/authentication/ @@ -14,7 +14,7 @@ This centralized user authentication is accomplished using the Rancher authentic ### External vs. Local Authentication -The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted. +The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted. | Auth Service | Available as of | | ------------------------------------------------------------------------------------------------ | ---------------- | diff --git a/content/rancher/v2.x/en/tools/drivers/_index.md b/content/rancher/v2.x/en/admin-settings/drivers/_index.md similarity index 99% rename from content/rancher/v2.x/en/tools/drivers/_index.md rename to content/rancher/v2.x/en/admin-settings/drivers/_index.md index 850e48749b6..6455e4d2b05 100644 --- a/content/rancher/v2.x/en/tools/drivers/_index.md +++ b/content/rancher/v2.x/en/admin-settings/drivers/_index.md @@ -1,6 +1,6 @@ --- title: Drivers -weight: 3500 +weight: 1140 --- Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes. diff --git a/content/rancher/v2.x/en/tools/drivers/cluster-drivers/_index.md b/content/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/drivers/cluster-drivers/_index.md rename to content/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/_index.md diff --git a/content/rancher/v2.x/en/tools/drivers/node-drivers/_index.md b/content/rancher/v2.x/en/admin-settings/drivers/node-drivers/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/drivers/node-drivers/_index.md rename to content/rancher/v2.x/en/admin-settings/drivers/node-drivers/_index.md diff --git a/content/rancher/v2.x/en/tools/globaldns/_index.md b/content/rancher/v2.x/en/admin-settings/globaldns/_index.md similarity index 99% rename from content/rancher/v2.x/en/tools/globaldns/_index.md rename to content/rancher/v2.x/en/admin-settings/globaldns/_index.md index 1ead3db8649..c83416309f6 100644 --- a/content/rancher/v2.x/en/tools/globaldns/_index.md +++ b/content/rancher/v2.x/en/admin-settings/globaldns/_index.md @@ -1,6 +1,6 @@ --- title: Global DNS -weight: 10005 +weight: 1145 --- _Available as of v2.2.0_ diff --git a/content/rancher/v2.x/en/admin-settings/log-in/_index.md b/content/rancher/v2.x/en/admin-settings/log-in/_index.md index 3a61c5404a4..c0adacd6d85 100644 --- a/content/rancher/v2.x/en/admin-settings/log-in/_index.md +++ b/content/rancher/v2.x/en/admin-settings/log-in/_index.md @@ -1,6 +1,6 @@ --- title: First Log In -weight: 50 +weight: 1105 aliases: - /rancher/v2.x/en/concepts/global-configuration/server-url/ - /rancher/v2.x/en/tasks/global-configuration/server-url/ @@ -9,4 +9,4 @@ aliases: After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself. ->**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care. \ No newline at end of file +>**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care. diff --git a/content/rancher/v2.x/en/admin-settings/rbac/_index.md b/content/rancher/v2.x/en/admin-settings/rbac/_index.md index 27c660aeb46..62867a8418e 100644 --- a/content/rancher/v2.x/en/admin-settings/rbac/_index.md +++ b/content/rancher/v2.x/en/admin-settings/rbac/_index.md @@ -1,6 +1,6 @@ --- -title: Roles in Rancher -weight: 1125 +title: Roles +weight: 1120 aliases: - /rancher/v2.x/en/concepts/global-configuration/users-permissions-roles/ --- diff --git a/content/rancher/v2.x/en/admin-settings/removing-rancher/_index.md b/content/rancher/v2.x/en/admin-settings/removing-rancher/_index.md deleted file mode 100644 index 22e572b83e0..00000000000 --- a/content/rancher/v2.x/en/admin-settings/removing-rancher/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Removing Rancher -weight: 5000 ---- - -When you deploy Rancher and use it to provision clusters, Rancher installs its components on the nodes you use. This section features instructions on how to remove Rancher's components from your nodes that you no longer want to use with Rancher. - -There are two contexts in which you'd remove Rancher from a Kubernetes cluster node. - -- [Removing Rancher Components from Rancher Launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/) - - In this context, you are removing Rancher components from Kubernetes clusters that you [launched using Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). - -- [Removing Rancher from Your Rancher Server Nodes]({{< baseurl >}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) - - In this context, you are removing Rancher from the Kubernetes cluster that you configured for your [Rancher installation]({{< baseurl >}}/rancher/v2.x/en/installation/ha/). diff --git a/content/rancher/v2.x/en/cli/_index.md b/content/rancher/v2.x/en/cli/_index.md index 62aabed313f..de92ac71134 100644 --- a/content/rancher/v2.x/en/cli/_index.md +++ b/content/rancher/v2.x/en/cli/_index.md @@ -1,11 +1,11 @@ --- -title: Rancher CLI +title: CLI weight: 6000 aliases: - /rancher/v2.x/en/concepts/cli-configuration/ --- -Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. +The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI. ### Download Rancher CLI diff --git a/content/rancher/v2.x/en/cluster-admin/_index.md b/content/rancher/v2.x/en/cluster-admin/_index.md new file mode 100644 index 00000000000..81b13b1540f --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/_index.md @@ -0,0 +1,70 @@ +--- +title: Cluster Administration +weight: 2005 +--- + +## What's a Kubernetes Cluster? + +A cluster is a group of computers that work together as a single system. + +A _Kubernetes Cluster_ is a cluster that uses the [Kubernetes container-orchestration system](https://kubernetes.io/) to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations. + +### Kubernetes Cluster Node Components + +Each computing resource in a Kubernetes Cluster is called a _node_. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: _etcd_ nodes, _control plane_ nodes, and _worker_ nodes. + +#### etcd Nodes + +[etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd) nodes run the etcd database. The etcd database component is a key value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. + +etcd is a distributed key value store, meaning it runs on multiple nodes so that there's always a backup available for fail over. Even though you can run etcd on a single node, you should run it on multiple nodes. We recommend 3, 5, or 7 etcd nodes for redundancy. + +#### Control Plane Nodes + +[Control plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane) nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although two or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles. + +#### Worker Nodes + +[Worker nodes](https://kubernetes.io/docs/concepts/architecture/nodes/) run: + +- _Kubelets_: An agent that monitors the state of the node, ensuring your containers are healthy. +- _Workloads_: The containers and pods that hold your apps, as well as other types of deployments. + +Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads. + +## Switching between Clusters + +To switch between clusters, use the drop-down available in the navigation bar. + +Alternatively, you can switch between projects and clusters directly in the navigation bar. Open the **Global** view and select **Clusters** from the main menu. Then open a cluster. + +## Managing Clusters in Rancher + +After clusters have been [provisioned into Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/), [cluster owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) will need to manage these clusters. + +| Action | [Rancher launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) | [Hosted Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) | [Imported Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters) | +| --- | --- | ---| ---| +| [Using kubeconfig file to access a Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/kubeconfig/) | * | * | * | +| [Using kubectl to Access a Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/kubectl/) | * | * | * | +| [Adding Cluster Members]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cluster-members/) | * | * | * | +| [Editing Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/editing-clusters/) | * | * | * | +| [Managing Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/nodes) | * | * | * | +| [Managing Persistent Volumes and Storage Classes]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/) | * | * | * | +| [Managing Projects and Namespaces]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/projects-and-namespaces/) | * | * | * | +| [Configuring Tools](#configuring-tools) | * | * | * | +| [Cloning Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cloning-clusters/)| | * | * | +| [Ability to rotate certificates]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/certificate-rotation/) | * | | | +| [Ability to back up your Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/) | * | | | +| [Recovering etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/recovering-etcd/) | * | | | +| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/) | * | | | + +## Configuring Tools + +Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories: + +- Alerts +- Notifiers +- Logging +- Monitoring + +For more information, see [Tools]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/) diff --git a/content/rancher/v2.x/en/tools/snapshots/_index.md b/content/rancher/v2.x/en/cluster-admin/backing-up-etcd/_index.md similarity index 77% rename from content/rancher/v2.x/en/tools/snapshots/_index.md rename to content/rancher/v2.x/en/cluster-admin/backing-up-etcd/_index.md index b7f47eb307d..94b2df550e4 100644 --- a/content/rancher/v2.x/en/tools/snapshots/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/backing-up-etcd/_index.md @@ -1,6 +1,6 @@ --- -title: Snapshots -weight: 10000 +title: Backing up etcd +weight: 2045 --- _Available as of v2.2.0_ @@ -61,26 +61,10 @@ Besides recurring snapshots, you might want to take a one-time snapshot in speci **Result:** Based on your [snapshot backup target](#snapshot-backup-targets), a one-time snapshot will be taken and saved in the selected backup target. -## Viewing Available snapshots +## Viewing Available Snapshots The list of all available snapshots for the cluster is available. 1. In the **Global** view, navigate to the cluster that you want to view snapshots. 2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created. - -## Restoring your Cluster from a Snapshot - -If your Kubernetes cluster is broken, you can restore the cluster from a snapshot. - -1. In the **Global** view, navigate to the cluster that you want to view snapshots. - -2. Click the **Vertical Ellipsis (...) > Restore Snapshot**. - -3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots. Click **Save**. - - > **Note:** Snapshots from S3 can only be restored from if the cluster is configured to take recurring snapshots on S3. - -**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state. - -> **Note:** If you are restoring a cluster with unavailable etcd nodes, it's recommended that all etcd nodes are removed from Rancher before attempting to restore. For clusters that were provisioned using [nodes hosted in an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/), new etcd nodes will automatically be created. For [custom clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/), please ensure that you add new etcd nodes to the cluster. diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/certificate-rotation/_index.md b/content/rancher/v2.x/en/cluster-admin/certificate-rotation/_index.md similarity index 99% rename from content/rancher/v2.x/en/cluster-provisioning/rke-clusters/certificate-rotation/_index.md rename to content/rancher/v2.x/en/cluster-admin/certificate-rotation/_index.md index 9ad8462ccc3..e45f9fd710f 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/certificate-rotation/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/certificate-rotation/_index.md @@ -1,6 +1,6 @@ --- title: Certificate Rotation -weight: 2245 +weight: 2040 --- _Available as of v2.2.0_ diff --git a/content/rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/_index.md b/content/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/_index.md similarity index 92% rename from content/rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/_index.md rename to content/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/_index.md index f9c39f956b3..e147062f684 100644 --- a/content/rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/cleaning-cluster-nodes/_index.md @@ -1,14 +1,13 @@ --- -title: Removing Rancher Components from Rancher Launched Kubernetes Nodes -weight: 375 +title: Cleaning up Clusters +weight: 2055 aliases: - - /rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/ - - /rancher/v2.x/en/installation/removing-rancher/ - /rancher/v2.x/en/faq/cleaning-cluster-nodes/ + - /rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/ --- -When you use Rancher to [launch nodes for a cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher), resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created. +When you use Rancher to [launch nodes for a cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher), resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created. -When removing nodes from your Rancher-launched cluster (provided that they are in `Active` state), those resources automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again. +When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in `Active` state), those resources automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again. ## What Gets Removed? @@ -59,11 +58,11 @@ For imported clusters, the process for removing Rancher from its nodes is a litt After you initiate the removal of an [imported cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) using the Rancher UI (or API), the following events occur. -1. Rancher creates a `serviceAccount` that it uses to remove the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the cluster. +1. Rancher creates a `serviceAccount` that it uses to remove the cluster. This account is assigned the [clusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) and [clusterRoleBinding](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#rolebinding-and-clusterrolebinding) permissions, which are required to remove the cluster. -1. Using the `serviceAccount`, Rancher schedules and runs a [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) that cleans the Rancher and Kubernetes components off of the node. This job also references the `serviceAccount` and its roles as dependencies, so the job deletes them before its completion. - -1. Rancher is removed from the cluster nodes. However, the cluster persists, running the native version of Kubernetes. +1. Using the `serviceAccount`, Rancher schedules and runs a [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) that cleans the Rancher and Kubernetes components off of the node. This job also references the `serviceAccount` and its roles as dependencies, so the job deletes them before its completion. + +1. Rancher is removed from the cluster nodes. However, the cluster persists, running the native version of Kubernetes. **Result:** All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted. @@ -89,7 +88,7 @@ Rather than cleaning imported cluster nodes using the Rancher UI, you can run a 1. From the same directory, run the script and provide the `rancher/rancher-agent` image version which should be equal to the version of Rancher used to manage the cluster. (``): - >**Tip:** + >**Tip:** > >Add the `-dry-run` flag to preview the script's outcome without making changes. ``` @@ -97,7 +96,7 @@ Rather than cleaning imported cluster nodes using the Rancher UI, you can run a ``` **Result:** The script runs. All components listed for imported clusters in [What Gets Removed?](#what-gets-removed) are deleted. - + {{% /tab %}} {{% /tabs %}} @@ -178,9 +177,9 @@ rm -rf /etc/ceph \ ### Network Interfaces and Iptables -The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. +The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. -This is the recommended method. +This is the recommended method. **To restart a node:** diff --git a/content/rancher/v2.x/en/cluster-provisioning/cloning-clusters/_index.md b/content/rancher/v2.x/en/cluster-admin/cloning-clusters/_index.md similarity index 98% rename from content/rancher/v2.x/en/cluster-provisioning/cloning-clusters/_index.md rename to content/rancher/v2.x/en/cluster-admin/cloning-clusters/_index.md index fb4025bc2b5..43c8dc93a5e 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/cloning-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/cloning-clusters/_index.md @@ -1,6 +1,8 @@ --- title: Cloning Clusters -weight: 2400 +weight: 2035 +aliases: + - /rancher/v2.x/en/cluster-provisioning/cloning-clusters/ --- If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/cluster-members/_index.md b/content/rancher/v2.x/en/cluster-admin/cluster-members/_index.md similarity index 98% rename from content/rancher/v2.x/en/k8s-in-rancher/cluster-members/_index.md rename to content/rancher/v2.x/en/cluster-admin/cluster-members/_index.md index 2831010a798..31e5fcb53d8 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/cluster-members/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/cluster-members/_index.md @@ -1,6 +1,6 @@ --- title: Adding Users to Clusters -weight: 100 +weight: 2020 aliases: - /rancher/v2.x/en/tasks/clusters/adding-managing-cluster-members/ - /rancher/v2.x/en/cluster-provisioning/cluster-members/ diff --git a/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md b/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md similarity index 98% rename from content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md rename to content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md index e5ced9bac94..8b78f3c800f 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/editing-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md @@ -1,6 +1,8 @@ --- title: Editing Clusters -weight: 200 +weight: 2025 +aliases: + - /rancher/v2.x/en/k8s-in-rancher/editing-clusters/ --- After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster. To edit your cluster, open the **Global** view, make sure the **Clusters** tab is selected, and then select **Ellipsis (...) > Edit** for the cluster that you want to edit. @@ -66,7 +68,7 @@ When editing clusters, clusters that are [launched using RKE]({{< baseurl >}}/ra ### Upgrading Kubernetes -Following an upgrade to the latest version of Rancher, you can update your existing clusters to use the latest supported version of Kubernetes. Before a new version of Rancher is released, it's tested with the latest versions of Kubernetes to ensure compatibility. +Following an upgrade to the latest version of Rancher, you can update your existing clusters to use the latest supported version of Kubernetes. Before a new version of Rancher is released, it's tested with the latest versions of Kubernetes to ensure compatibility. >**Recommended:** Before upgrading Kubernetes, [backup your cluster]({{< baseurl >}}/rancher/v2.x/en/backups). @@ -78,7 +80,7 @@ Following an upgrade to the latest version of Rancher, you can update your exist 1. Click **Save**. -**Result:** Kubernetes begins upgrading for the cluster. During the upgrade, your cluster is unavailable. +**Result:** Kubernetes begins upgrading for the cluster. During the upgrade, your cluster is unavailable. ### Adding a Pod Security Policy @@ -96,7 +98,7 @@ You can assign a pod security policy when you provision a cluster. However, if y 4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster. - Rancher ships with [policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) of `restricted` and `unrestricted`, although you can [create custom policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) as well. + Rancher ships with [policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) of `restricted` and `unrestricted`, although you can [create custom policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/#default-pod-security-policies) as well. 5. Click **Save**. @@ -149,7 +151,7 @@ In clusters [launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioni - Add new [pools of nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to your cluster. The nodes added to the pool are provisioned according to the [node template]({{< baseurl >}}/rancher/v2.x/en/user-settings/node-templates/) that you use. - Click **+** and follow the directions on screen to create a new template. - + - You can also reuse existing templates by selecting one from the **Template** drop-down. - Redistribute Kubernetes roles amongst your node pools by making different checkbox selections @@ -157,4 +159,3 @@ In clusters [launched by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioni - Scale the number of nodes in a pool up or down (although, if you simply want to maintain your node scale, we recommend using the cluster's [Nodes tab]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/nodes/#nodes-provisioned-by-node-pool) instead.) >**Note:** The Node Pools section is not available for imported clusters or clusters hosted by a Kubernetes provider. - diff --git a/content/rancher/v2.x/en/k8s-in-rancher/kubeconfig/_index.md b/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md similarity index 97% rename from content/rancher/v2.x/en/k8s-in-rancher/kubeconfig/_index.md rename to content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md index b26a607162e..17b63934f43 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/kubeconfig/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/kubeconfig/_index.md @@ -1,8 +1,9 @@ --- -title: Kubeconfig Files -weight: 3010 +title: Kubeconfig File +weight: 2010 aliases: - /rancher/v2.x/en/concepts/clusters/kubeconfig-files/ + - /rancher/v2.x/en/k8s-in-rancher/kubeconfig/ --- A _kubeconfig file_ is a file used to configure access to Kubernetes when used in conjunction with the kubectl commandline tool (or other clients). diff --git a/content/rancher/v2.x/en/k8s-in-rancher/kubectl/_index.md b/content/rancher/v2.x/en/cluster-admin/kubectl/_index.md similarity index 98% rename from content/rancher/v2.x/en/k8s-in-rancher/kubectl/_index.md rename to content/rancher/v2.x/en/cluster-admin/kubectl/_index.md index 3d26fa5c665..2d332ac495a 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/kubectl/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/kubectl/_index.md @@ -1,8 +1,9 @@ --- title: Using kubectl to Access a Cluster -weight: 3005 +weight: 2015 aliases: - /rancher/v2.x/en/tasks/clusters/using-kubectl-to-access-a-cluster/ + - /rancher/v2.x/en/k8s-in-rancher/kubectl/ --- You can access and manage your Kubernetes clusters using kubectl in two ways: diff --git a/content/rancher/v2.x/en/k8s-in-rancher/nodes/_index.md b/content/rancher/v2.x/en/cluster-admin/nodes/_index.md similarity index 98% rename from content/rancher/v2.x/en/k8s-in-rancher/nodes/_index.md rename to content/rancher/v2.x/en/cluster-admin/nodes/_index.md index 32a960e0831..8a64ce98590 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/nodes/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/nodes/_index.md @@ -1,7 +1,8 @@ --- title: Nodes -weight: +weight: 2030 aliases: + - /rancher/v2.x/en/k8s-in-rancher/nodes/ --- After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's **Node** tab. Depending on the [option used]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-in-rancher) to provision the cluster, there are different node options available. @@ -41,8 +42,8 @@ _Draining_ is the process of first cordoning the node, and then evicting all its - For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod. - For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it. - -You can drain nodes that are in either a `cordoned` or `active` state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods. + +You can drain nodes that are in either a `cordoned` or `active` state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods. However, you can override the conditions draining when you initiate the drain (see [below](#below)). You're also given an opportunity to set a grace period and timeout value. @@ -52,7 +53,7 @@ However, you can override the conditions draining when you initiate the drain (s The following list describes each drain option: - **Even if there are pods not managed by a ReplicationController, ReplicaSet, Job, DaemonSet or StatefulSet** - + These types of pods won't get rescheduled to a new node, since they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods. Kubernetes forces you to choose this option (which will delete/evict these pods) or drain won't proceed. - **Even if there are DaemonSet-managed pods** @@ -60,12 +61,12 @@ The following list describes each drain option: Similar to above, if you have any daemonsets, drain would proceed only if this option is selected. Even when this option is on, pods won't be deleted since they'll immediately be replaced. On startup, Rancher currently has a few daemonsets running by default in the system, so this option is turned on by default. - **Even if there are pods using emptyDir** - - If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Similar to the first option, Kubernetes expects the implementation to decide what to do with these pods. Choosing this option will delete these pods. + + If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Similar to the first option, Kubernetes expects the implementation to decide what to do with these pods. Choosing this option will delete these pods. - **Grace Period** - The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used. + The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used. - **Timeout** @@ -128,10 +129,10 @@ For [nodes hosted by an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en ``` ## Notes for Node Pool Nodes - -Clusters provisioned using [one of the node pool options]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-pools) automatically maintain the node scale that's set during the initial cluster provisioning. This scale determines the number of active nodes that Rancher maintains for the cluster. - +Clusters provisioned using [one of the node pool options]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-pools) automatically maintain the node scale that's set during the initial cluster provisioning. This scale determines the number of active nodes that Rancher maintains for the cluster. + + ## Notes for Nodes Provisioned by Hosted Kubernetes Providers Options for managing nodes [hosted by a Kubernetes provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly. @@ -140,4 +141,3 @@ Options for managing nodes [hosted by a Kubernetes provider]({{< baseurl >}}/ran ## Notes for Imported Nodes Although you can deploy workloads to an [imported cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/) using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher. - diff --git a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/_index.md b/content/rancher/v2.x/en/cluster-admin/projects-and-namespaces/_index.md similarity index 69% rename from content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/_index.md rename to content/rancher/v2.x/en/cluster-admin/projects-and-namespaces/_index.md index a10813563d5..592ea784b6b 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/projects-and-namespaces/_index.md @@ -1,15 +1,16 @@ --- title: Projects and Namespaces -weight: 3020 +weight: 2032 aliases: - /rancher/v2.x/en/concepts/projects/ - /rancher/v2.x/en/tasks/projects/ - /rancher/v2.x/en/tasks/projects/create-project/ + - /rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/ --- ## Projects -_Projects_ are organizational objects introduced in Rancher that ease the administrative burden of your cluster. You can use projects to support multi-tenancy. +_Projects_ are organizational objects introduced in Rancher that ease the administrative burden of your cluster. You can use projects to support multi-tenancy. Projects provide an extra level of organization in your Kubernetes clusters beyond [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). In terms of hierarchy: @@ -23,7 +24,7 @@ Rancher projects resolve this issue by allowing you to apply resources and acces You can use projects to perform actions like: - Assign users access to a group of namespaces (i.e., [project membership]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members)). -- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). +- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). - Assign resources to the project. - Assign Pod Security Policies. @@ -31,7 +32,7 @@ You can use projects to perform actions like: When you create a cluster, two project are automatically created within it: - [Default Project](#default-project) -- [System Project](#system-project) +- [System Project](#system-project) ### Default Project @@ -44,7 +45,7 @@ _Available as of v2.0.7_ When troubleshooting, you can view the `system` project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers. -To open it, open the **Global** menu, and then select the `system` project for your cluster. +To open it, open the **Global** menu, and then select the `system` project for your cluster. The `system` project: @@ -58,11 +59,11 @@ The `system` project: > - The [Canal network plug-in]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#canal) is in use. > - The Project Network Isolation option is enabled. > ->The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health. +>The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health. ### Authorization -Non-administrative users are only authorized for project access after an administrator explicitly adds them to the project's **Members** tab. +Non-administrative users are only authorized for project access after an administrator, cluster owner or cluster member explicitly adds them to the project's **Members** tab. >**Exception:** > Non-administrative users can access projects that they create themselves. @@ -100,9 +101,9 @@ Rancher extends Kubernetes to allow the application of [Pod Security Policies](h >**Note:** You can only search for groups if external authentication is enabled. 1. From the **Role** drop-down, choose a role. - + [What are Roles?]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/) - + >**Notes:** > >- Users assigned the `Owner` or `Member` role for a project automatically inherit the `namespace creation` role. However, this role is a [Kubernetes ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the `Owner` or `Member` role for a project can create namespaces in other projects they're assigned to, even with only the `Read Only` role assigned. @@ -110,22 +111,22 @@ Rancher extends Kubernetes to allow the application of [Pod Security Policies](h >- Choose `Custom` to create a custom role on the fly: [Custom Project Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#custom-project-roles). 1. To add more members, repeat substeps a—c. - + 1. **Optional:** Add **Resource Quotas**, which limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas). >**Note:** This option is available as of v2.1.0. 1. Click **Add Quota**. - + 1. Select a [Resource Type]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#resource-quota-types). - + 1. Enter values for the **Project Limit** and the **Namespace Default Limit**. - + | Field | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------- | | Project Limit | The overall resource limit for the project. | - | Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. | - + | Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. | + 1. **Optional:** Repeat these substeps to add more quotas. 1. **Optional:** Specify **Container Default Resource Limit**, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see [Container Default Resource Limit]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#setting-container-default-resource-limit) @@ -136,7 +137,7 @@ Rancher extends Kubernetes to allow the application of [Pod Security Policies](h **Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view. -## Switching Clusters/Projects +## Switching between Clusters/Projects To switch between clusters and projects, use the **Global** drop-down available in the main menu. @@ -166,61 +167,4 @@ Resources that you can assign directly to namespaces include: >**Note:** Although you can assign role-based access to namespaces in the base version of Kubernetes, you cannot assign roles to namespaces in Rancher. Instead, assign role-based access at the project level. -### Creating Namespaces - -Create a new namespace to isolate apps and resources in a project. - ->**Tip:** When working with project resources that you can assign to a namespace (i.e., [workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/), [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/configmaps), etc.) you can create a namespace on the fly. - -1. From the **Global** view, open the project where you want to create a namespace. - - >**Tip:** As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can can create them from the cluster level as well. - -1. From the main menu, select **Namespace**. The click **Add Namespace**. - -1. **Optional:** If your project has [Resource Quotas]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas) in effect, you can override the default resource **Limits** (which places a cap on the resources that the namespace can consume). - -1. Enter a **Name** and then click **Create**. - -**Result:** Your namespace is added to the project. You can begin assigning cluster resources to the namespace. - -### Moving Namespaces to Another Project - -Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application. - -1. From the **Global** view, open the cluster that contains the namespace you want to move. - -1. From the main menu, select **Projects/Namespaces**. - -1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one. - - >**Notes:** - > - >- Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking. - >- You cannot move a namespace into a project that already has a [resource quota]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/) configured. - >- If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace. - -1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**. - -**Result:** Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project. - -### Editing Namespace Resource Quotas - -If there is a [resource quota]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas) configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources. - -1. From the **Global** view, open the cluster that contains the namespace for which you want to edit the resource quota. - -1. From the main menu, select **Projects/Namespaces**. - -1. Find the namespace for which you want to edit the resource quota. Select **Ellipsis (...) > Edit**. - -1. Edit the Resource Quota **Limits**. These limits determine the resources available to the namespace. The limits must be set within the configured [project limits]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#project-limits). - - For more information about each **Resource Type**, see [Resource Quota Types]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#resource-quota-types). - - >**Note:** - > - >- If a resource quota is not configured for the project, these options will not be available. - >- If you enter limits that exceed the configured project limits, Rancher will not let you save your edits. - -**Result:** The namespace's default resource quota is overwritten with your override. +For more information, see [Namespaces]({{< baseurl >}}/rancher/v2.x/en/project-admin/namespaces/). diff --git a/content/rancher/v2.x/en/cluster-admin/recovering-etcd/_index.md b/content/rancher/v2.x/en/cluster-admin/recovering-etcd/_index.md new file mode 100644 index 00000000000..3f15a194e89 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/recovering-etcd/_index.md @@ -0,0 +1,64 @@ +--- +title: Recovering etcd +weight: 2050 +--- + +_Available as of v2.2.0_ + +etcd backup and recovery for [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) can be easily performed. Snapshots of the etcd database are taken and saved either [locally on to the etcd nodes](#test) or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster. + +Rancher recommends enabling the [ability to set up recurring snapshots of etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#configuring-recurring-snapshots-for-the-cluster), but [one-time snapshots]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/#one-time-snapshots) can easily be taken as well. Rancher allows restore from [saved snapshots](##restoring-your-cluster-from-a-snapshot) or if you don't have any snapshots, you can still [restore etcd](#recovering-etcd-without-a-snapshot). + +## Viewing Available Snapshots + +The list of all available snapshots for the cluster is available. + +1. In the **Global** view, navigate to the cluster that you want to view snapshots. + +2. Click **Tools > Snapshots** from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created. + +## Restoring your Cluster from a Snapshot + +If your Kubernetes cluster is broken, you can restore the cluster from a snapshot. + +1. In the **Global** view, navigate to the cluster that you want to view snapshots. + +2. Click the **Vertical Ellipsis (...) > Restore Snapshot**. + +3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots. Click **Save**. + + > **Note:** Snapshots from S3 can only be restored from if the cluster is configured to take recurring snapshots on S3. + +**Result:** The cluster will go into `updating` state and the process of restoring the `etcd` nodes from the snapshot will start. The cluster is restored when it returns to an `active` state. + +> **Note:** If you are restoring a cluster with unavailable etcd nodes, it's recommended that all etcd nodes are removed from Rancher before attempting to restore. For clusters that were provisioned using [nodes hosted in an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/), new etcd nodes will automatically be created. For [custom clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/), please ensure that you add new etcd nodes to the cluster. + +## Recovering etcd without a Snapshot + +If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. Please review the best practices for the what the [number of etcd nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/production/#count-of-etcd-nodes) should be in a Kubernetes cluster. If you want to recover your set of etcd nodes, follow these instructions: + +1. Keep only one etcd node in the cluster by removing all other etcd nodes. + +2. On the single remaining etcd node, run the following command: + + ``` + $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd + ``` + + This command outputs the running command for etcd, save this command to use later. + +3. Stop the etcd container that you launched in the previous step and rename it to `etcd-old`. + + ``` + $ docker stop etcd + $ docker rename etcd etcd-old + ``` + +4. Take the saved command from Step 2 and revise it: + + - If you originally had more than 1 etcd node, then you need to change `--initial-cluster` to only contain the node that remains. + - Add `--force-new-cluster` to the end of the command. + +5. Run the revised command. + +6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/) and you want to reuse an old node, you are required to [clean up the nodes]({{< baseurl >}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) before attempting to add them back into a cluster. diff --git a/content/rancher/v2.x/en/tools/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/_index.md similarity index 60% rename from content/rancher/v2.x/en/tools/_index.md rename to content/rancher/v2.x/en/cluster-admin/tools/_index.md index dc7c2603405..e996259a053 100644 --- a/content/rancher/v2.x/en/tools/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/_index.md @@ -1,28 +1,22 @@ --- -title: Rancher Tools -weight: 5000 +title: Configuring Tools +weight: 2033 +aliases: + - /rancher/v2.x/en/tools/ + - /rancher/v2.x/en/tools/notifiers-and-alerts/ --- Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories: -- [Drivers](#drivers) + - [Alerts](#alerts) - [Notifiers](#notifiers) - [Logging](#logging) -- [Pipelines](#pipelines) - [Monitoring](#monitoring) -- [Global DNS](#global-dns) -- [Snapshots](#Snapshots) -## Drivers - -Drivers in Rancher allow you to manage which providers can be used to deploy [hosted Kubernetes clusters]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes. - -For more information, see [Drivers]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/). - ## Alerts To keep your clusters and applications healthy and driving your organizational productivity forward, you need stay informed of events occurring in your clusters, both planned and unplanned. To help you stay informed of these events, Rancher allows you to configure alerts. @@ -40,7 +34,7 @@ When an event occurs, your alert is triggered, and you are sent a notification. Additionally, 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. -For more information, see [Alerts]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#alerts). +You can configure alerts at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/alerts/). ## Notifiers @@ -54,7 +48,7 @@ _Notifiers_ are services that inform you of alert events. You can configure noti - Webhooks: Update a webpage with alert notifications. - WeChat: Send alert notifications to your Enterprise WeChat contacts. -For more information, see [Notifiers]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#notifiers). +For more information, see [Notifiers]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/notifiers/). ## Logging @@ -70,21 +64,7 @@ These services collect container log events, which are saved to the `/var/log/co 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. -You can configure these services to collect logs at either the cluster or project level. - -## Pipelines - -Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline. - -To set up a pipeline, you'll first need to authorize Rancher using your GitHub settings. Directions are provided in the Rancher UI. After authorizing Rancher in GitHub, provide Rancher with a client ID and secret to authenticate. - -After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution: - -- Build your application from code to image. -- Validate your builds. -- Deploy your build images to your cluster. -- Run unit tests. -- Run regression tests. +You can configure these services to collect logs at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/logging/). ## Monitoring @@ -94,22 +74,4 @@ Using Rancher, you can monitor the state and processes of your cluster nodes, Ku In other words, Prometheus let's you view metrics from your different Rancher and Kubernetes objects. Using timestamps, you can 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 and project-only Prometheus instances are also supported. -For more information, see the [Monitoring Documentation]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring). - -## Global DNS - -_Available as v2.2.0_ - -When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS. - -For more information on how to use this feature, see [Global DNS]({{< baseurl >}}/rancher/v2.x/en/tools/globaldns/). - -## Snapshots - -_Available as v2.2.0_ - -For [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the etcd database can be backed up by enabling the ability to take recurring snapshots. Clusters can be configured to have these snapshots saved locally on the etcd nodes or saved to an external S3 compatible provider. - -When needed, these snapshots can be used to restore existing set of etcd nodes in your [Rancher launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). If all the etcd nodes are down, a snapshot, that was backed up remotely, can be used on a new set of etcd nodes. - -For more information on how to use this feature, see [Snapshots]({{< baseurl >}}/rancher/v2.x/en/tools/snapshots/). +You can configure these services to collect logs at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/monitoring/). diff --git a/content/rancher/v2.x/en/cluster-admin/tools/alerts/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/alerts/_index.md new file mode 100644 index 00000000000..24988ea62d6 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/alerts/_index.md @@ -0,0 +1,214 @@ +--- +title: Alerts +weight: 2 +--- + +Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Notifiers are objects that you configure to leverage popular IT services, which send you notification of Rancher events. Alerts are rule sets that trigger when those notifications are sent. + +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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) and [project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) of events they need to address. + +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. To help you stay informed of these events, you can configure alerts. + +Alerts are sets of rules, chosen by you, to monitor for specific events. The scope for alerts can be set at either the cluster or [project]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/alerts/) level. + +At the cluster level, Rancher monitors components in your Kubernetes cluster, and sends you alerts related to: + +- The state of your nodes. +- The system services that manage your Kubernetes cluster. +- The resource events from specific system services. +- The Prometheus expression cross the thresholds + +
+
+ +## Adding Cluster Alerts + +As a cluster owner, you can configure Rancher to send you alerts for cluster events. + +>**Prerequisite:** Before you can receive cluster alerts, you must [add a notifier]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/notifiers/#adding-notifiers). + +1. From the **Global** view, open the cluster that you want to configure alerts for. + +1. From the main menu, 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, complete one of the instruction subsets below. +{{% accordion id="system-service" label="System Service Alerts" %}} +This alert type monitor for events that affect one of the Kubernetes master components, regardless of the node it occurs on. + +1. Select the **System Services** option, and then select an option from the drop-down. + + - [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) + +1. 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. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="resource-event" label="Resource Event Alerts" %}} +This alert type monitors for specific events that are thrown from a resource type. + +1. 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. + +1. 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/) + +1. 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**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="node" label="Node Alerts" %}} +This alert type monitors for events that occur on a specific node. + +1. Select the **Node** option, and then make a selection from the **Choose a Node** drop-down. + +1. 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. + +1. 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**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="node-selector" label="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/). + +1. 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. + +1. 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. + +1. 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**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="cluster-expression" label="Metric Expression Alerts" %}} +This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring. + +1. Input or select an **Expression**, the drop down shows the original metrics from Prometheus, including: + + - [**Node**](https://github.com/prometheus/node_exporter) + - [**Container**](https://github.com/google/cadvisor) + - [**ETCD**](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/monitoring.md) + - [**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]({{< baseurl >}}/rancher/v2.x/en/tools/logging)) + - [**Cluster Level Grafana**](http://docs.grafana.org/administration/metrics/) + - **Cluster Level Prometheus** + +1. 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. + +1. Input a **Threshold**, for trigger alert when the value of expression cross the threshold. + +1. Choose a **Comparison**. + +1. Select a duration, for trigger alert when expression value crosses the threshold longer than the configured duration. + +1. 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**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} + +1. Continue adding more **Alert Rule** to the group. + +1. Finally, choose the notifiers that send you alerts. + + - You can set up multiple notifiers. + - You can change notifier recipients on the fly. + +**Result:** Your alert is configured. A notification is sent when the alert is triggered. + +## 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 diff --git a/content/rancher/v2.x/en/tools/logging/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/_index.md similarity index 94% rename from content/rancher/v2.x/en/tools/logging/_index.md rename to content/rancher/v2.x/en/cluster-admin/tools/logging/_index.md index ae4bf31420b..426e0aa1b9f 100644 --- a/content/rancher/v2.x/en/tools/logging/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/_index.md @@ -1,8 +1,9 @@ --- title: Logging -weight: 5015 +weight: 3 aliases: - /rancher/v2.x/en/tasks/logging/ + - /rancher/v2.x/en/tools/logging/ --- Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. @@ -12,8 +13,8 @@ Rancher supports the following services: - [Elasticsearch]({{< baseurl >}}/rancher/v2.x/en/tools/logging/elasticsearch) - [Splunk]({{< baseurl >}}/rancher/v2.x/en/tools/logging/splunk) - [Kafka]({{< baseurl >}}/rancher/v2.x/en/tools/logging/kafka) -- [Syslog]({{< baseurl >}}/rancher/v2.x/en/tools/logging/syslog) -- [Fluentd]({{< baseurl >}}/rancher/v2.x/en/tools/logging/fluentd) +- [Syslog]({{< baseurl >}}/rancher/v2.x/en/tools/logging/syslog) +- [Fluentd]({{< baseurl >}}/rancher/v2.x/en/tools/logging/fluentd) ## Requirements @@ -41,11 +42,11 @@ You can configure logging at either cluster or project level. - If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. - Cluster logging writes logs for every pod in the cluster and, in [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), Kubernetes system components. Logs from the following locations are sent to your logging service: + Cluster logging writes logs for every pod in the cluster and, in [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), Kubernetes system components. Logs from the following locations are sent to your logging service: - The `/var/log/containers` path for pod logging. - + - The `/var/lib/rancher/rke/logs/` path for Kubernetes system components. - If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. @@ -56,4 +57,4 @@ After collection, all logs are stored by your logging service. Log into your ser ## Related Links -[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/) \ No newline at end of file +[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/) diff --git a/content/rancher/v2.x/en/cluster-admin/tools/logging/custom/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/custom/_index.md new file mode 100644 index 00000000000..c78302fb630 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/custom/_index.md @@ -0,0 +1,90 @@ +--- +title: Custom +weight: 700 +--- + +_Available as of v2.2.0_ + +You can configure Rancher to send Kubernetes logs to Elasticsearch, Splunk, Kafka, Syslog or Fluentd. + +## Configuring Advance Mode + +You can configure Rancher to send cluster or project logs to one of the logging targets in advance mode by inputting raw fluentd configuration. + +>**Prerequisite:** You must have a one of the logging targets of Elasticsearch, Splunk, Kafka, Syslog and Fluentd server configured. + +1. Browse to the cluster or project. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. + +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. + +{{% /accordion %}} + +1. Select one of the logging targets, giving example for **Elasticsearch**. + +1. Click the **Edit as File**. + + 1. Input the Fluentd output configuration. + + 1. Giving an example for **Elasticsearch** target. + + ```sh + @type elasticsearch + include_tag_key true + user elasticsearch + password PleaseChaneMe + hosts https://rancher.com:9200 + logstash_format true + logstash_prefix elastic-index + logstash_dateformat %Y-%m-%d + type_name container_log + + ``` + + 1. For Elasticsearch configuration, see [Elasticsearch Documentation](https://github.com/uken/fluent-plugin-elasticsearch) for details. + + 1. For Splunk configuration, see [Splunk Documentation](https://github.com/fluent/fluent-plugin-splunk) for details. + + 1. For Kafka configuration, see [Kafka Documentation](https://github.com/fluent/fluent-plugin-kafka) for details. + + 1. For Syslog configuration, see [Syslog Documentation](https://github.com/dlackty/fluent-plugin-remote_syslog) for details. + + 1. For Fluentd configuration, see [Fluentd Documentation](https://docs.fluentd.org/v1.0/articles/out_forward) for details. + +1. If your logging server is using TLS, you need to complete the **SSL Configuration** form. + + 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. + + 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. If you are using a self-signed certificate, you need to provide the **CA Certificate PEM** as well. + +1. 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 **Dry Run**. Rancher calls the fluentd dry run command to validate the configuration. + +1. Click **Save**. + +**Result:** Rancher is now configured to send logs to your configured server. View your server to see logs for your cluster and containers. diff --git a/content/rancher/v2.x/en/cluster-admin/tools/logging/elasticsearch/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/elasticsearch/_index.md new file mode 100644 index 00000000000..e97fd6e7d4c --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/elasticsearch/_index.md @@ -0,0 +1,73 @@ +--- +title: Elasticsearch +weight: 200 +aliases: + - /rancher/v2.x/en/tools/logging/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 for your cluster or container. + +## Configuring Elasticsearch Logging + +You can configure Rancher to send logs from your cluster or project to your instance of Elasticsearch. + +>**Prerequisites:** Configure an [Elasticsearch deployment](https://www.elastic.co/guide/en/cloud/saas-release/ec-create-deployment.html). + +1. Browse to the cluster or project that you want to log. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. In versions prior to v2.2.0, you can choose **Resources > Logging**. +{{% /accordion %}} + +1. Select **Elasticsearch**. + +1. Complete the **Elasticsearch Configuration** form. + + 1. From the **Endpoint** field, enter the IP address and port for your Elasticsearch instance. You can copy 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). + +1. If your instance of Elasticsearch uses SSL, complete the **SSL Configuration** form. + + 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. + + 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. If you are using a self-signed certificate, you need to provide the **CA Certificate PEM** as well. + + 1. Enter your private key password. + + 1. Enter your ssl version. The default version is tlsv1_2. + + 1. Select the **Enabled - Input trusted server certificate** option and enter your **Trusted Server Certificate Chain** if you are using a certificate from a certificate authority. + +1. 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 Elasticsearch. + +1. Click **Save**. + +**Result:** Rancher is now configured to send cluster and container logs to Elasticsearch. Log into Elasticsearch or Kibana to view your cluster/project logs. diff --git a/content/rancher/v2.x/en/cluster-admin/tools/logging/fluentd/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/fluentd/_index.md new file mode 100644 index 00000000000..ee73badd537 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/fluentd/_index.md @@ -0,0 +1,68 @@ +--- +title: Fluentd +weight: 600 +--- + +If your organization is using [Fluentd](https://www.fluentd.org/), you can configure Rancher to send logs to Fluentd server. + +## Configuring Fluentd Logging + +You can configure Rancher to send Kubernetes logs to your Fluentd. + +>**Prerequisites:** Configure Fluentd input forward to receive the event stream. +> +>See [Fluentd Documentation](https://docs.fluentd.org/v1.0/articles/in_forward) for details. + +1. Browse to the cluster or project that you want to log. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. In versions prior to v2.2.0, you can choose **Resources > Logging**. +{{% /accordion %}} + +1. Select **Fluentd**. + +1. Complete the **Fluentd Server Configuration** form. + + 1. From the **Endpoint** field, enter the address of you Fluentd instance (i.e. `http://Fluentd-server:24224`). + + 1. Enter the **Shared Key** if your Fluentd Server is using shared key for authentication. + + 1. Enter the **Username** and **Password** if your Fluentd Server is using username and pasword for authentication. + + 1. **Optional:** Enter the **Hostname** of the server. + + 1. Enter the load balancing **Weight** of the server. If the weight of one server is 20 and the other server is 30, events will be sent in a 2:3 ratio. The default weight is 60 if you leave this field empty. + + 1. Check **Use as Standby Only** if this server is standby. Standby servers will be used when all non-standby servers are down. + + 1. You can add multiple Fluentd servers. + +1. Select **Enable Gzip Compression**. The transferred payload size will be reduced. + +1. If your Fluentd is using SSL, you need to complete the **SSL Configuration** form. + + 1. If you are using a self-signed certificate, you need to provide the **CA Certificate PEM** as well. + +1. 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 event 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 Fluentd with rancher tag. + +1. Click **Save**. + +**Result:** Rancher is now configured to send logs to Fluentd. Check you Fluentd output events for your cluster and containers. diff --git a/content/rancher/v2.x/en/cluster-admin/tools/logging/kafka/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/kafka/_index.md new file mode 100644 index 00000000000..cda52889235 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/kafka/_index.md @@ -0,0 +1,75 @@ +--- +title: Kafka +weight: 400 +aliases: + - /rancher/v2.x/en/tools/logging/kafka/ +--- + +You can configure Rancher to send cluster or project logs to a [Kafka](https://kafka.apache.org/) server. + +## Configuring Kafka Logging + +>**Prerequisite:** You must have a Kafka server configured. + +1. Browse to the cluster or project that you want to log. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. In versions prior to v2.2.0, you can choose **Resources > Logging**. +{{% /accordion %}} + +1. Select **Kafka**. + +1. Complete the **Kafka Configuration** form. + + 1. From **Endpoint Type**, select the type of Kafka server you are using: **Zookeeper** or **Broker**. + + 1. From the **Endpoint** field, enter the IP address and the port for your Zookeeper or Broker. For Broker type, you can add multiple endpoints. + + By default, Zookeeper uses port `2181`, Kafka broker uses port `9092`. Please note that Zookeeper endpoint is for Kafka cluster not enable tls. + + 1. From 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. + +1. If your Kafka cluster is using SSL for **Broker**, you need to complete the **SSL Configuration** form. + + 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. + + 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. If you are using a self-signed certificate, you need to provide the **CA Certificate PEM** as well. + +1. If your Kafka cluster is using SASL authentication for **Broker**, you need to complete the **SASL Configuration** form. See [Kafka SASL](https://kafka.apache.org/documentation/#security_sasl) for details. + + 1. Enter SASL **Username** and **Passwork** + + 1. Select **SASL Type** which your Kafka is using. Please make sure your Kafka cluster is using SSL when you select **Plain**. + + 1. If your Kafka is using **Scram**, you need to select which **Scram Mechanism** Kafka is using. + +1. 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 logs 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 Kafka. + +1. Click **Save**. + +**Result:** Rancher is now configured to send logs to Kafka. View your Kafka stream to view logs for your cluster and containers. diff --git a/content/rancher/v2.x/en/tools/logging/splunk/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/splunk/_index.md old mode 100755 new mode 100644 similarity index 96% rename from content/rancher/v2.x/en/tools/logging/splunk/_index.md rename to content/rancher/v2.x/en/cluster-admin/tools/logging/splunk/_index.md index 1765a0080b4..8fd05ea432c --- a/content/rancher/v2.x/en/tools/logging/splunk/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/splunk/_index.md @@ -3,6 +3,7 @@ title: Splunk weight: 300 aliases: - /rancher/v2.x/en/tasks/logging/splunk/ + - /rancher/v2.x/en/tools/logging/splunk/ --- If your organization uses [Splunk](https://www.splunk.com/), you can configure Rancher to send it cluster or project logs. Afterwards logs are sent, you can use Splunk to view them. @@ -11,10 +12,10 @@ If your organization uses [Splunk](https://www.splunk.com/), you can configure R You can configure Rancher to send Kubernetes logs to your instance of Splunk. ->**Prerequisites:** +>**Prerequisites:** > ->- Configure HTTP event collection for your Splunk Server (Splunk Enterprise or Splunk Cloud). ->- Enable all tokens, and then create a new token. +>- Configure HTTP event collection for your Splunk Server (Splunk Enterprise or Splunk Cloud). +>- Enable all tokens, and then create a new token. > >For more information, see [Splunk Documentation](http://docs.splunk.com/Documentation/Splunk/7.1.2/Data/UsetheHTTPEventCollector#About_Event_Collector_tokens). @@ -39,7 +40,7 @@ If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-sett 1. Complete the **Splunk HTTP Event Collector Configuration** form. 1. From 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). @@ -48,14 +49,14 @@ If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-sett 1. **Optional:** Enter one or more [index](http://docs.splunk.com/Documentation/Splunk/7.1.2/Indexer/Aboutindexesandindexers) that's allowed for your token. -1. If your Splunk is using SSL, you need to complete the **SSL Configuration** form. +1. If your Splunk is using SSL, you need to complete the **SSL Configuration** form. 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. 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 private key password. diff --git a/content/rancher/v2.x/en/cluster-admin/tools/logging/syslog/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/logging/syslog/_index.md new file mode 100644 index 00000000000..afe380c15fa --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/logging/syslog/_index.md @@ -0,0 +1,74 @@ +--- +title: Syslog +weight: 500 +aliases: + - /rancher/v2.x/en/tools/logging/syslog/ +--- + +You can configure Rancher to send Kubernetes logs to a [Syslog](https://tools.ietf.org/html/rfc5424) server. + +## Configuring Syslog + +You can configure Rancher to send cluster or project logs to Syslog. + +>**Prerequisite:** You must have a Syslog server configured. + +1. Browse to the cluster or project that you want to log. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. + +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. In versions prior to v2.2.0, you can choose **Resources > Logging**. + +{{% /accordion %}} + +1. Select **Syslog**. + +1. Complete the **Syslog Configuration** form. + + 1. From the **Endpoint** field, enter the IP address and port for your Syslog server. Additionally, select the protocol that your Syslog server uses from the drop-down. + + 1. From the **Program** field, enter the name of the application sending logs to your Syslog server (i.e., Rancher). + + 1. If you are using a cloud logging service (i.e., [Sumologic](https://www.sumologic.com/)), enter a **Token** that authenticates with your Syslog server. Use the cloud logging service to create this token. + + 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). + +1. If your Syslog is using **TCP** protocol, you need to select **Use TLS** and complete the **SSL Configuration** form. + + 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. + + 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 private key password. + + 1. If you are using a self-signed certificate, you need to select the **Enabled - Input trusted server certificate** option and enter your **CA Certificate PEM**. + + 1. If you are using rsyslog, please make sure your rsyslog authentication mode is **x509/name**. + +1. 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 Syslog. + +1. Click **Save**. + +**Result:** Rancher is now configured to send logs to your Syslog server. View your Syslog stream to view logs for your cluster and containers. diff --git a/content/rancher/v2.x/en/tools/monitoring/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/monitoring/_index.md similarity index 99% rename from content/rancher/v2.x/en/tools/monitoring/_index.md rename to content/rancher/v2.x/en/cluster-admin/tools/monitoring/_index.md index 8c6f3acaee9..45b6cbc8659 100644 --- a/content/rancher/v2.x/en/tools/monitoring/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/tools/monitoring/_index.md @@ -1,6 +1,6 @@ --- title: Monitoring -weight: 10000 +weight: 4 --- _Available as of v2.2.0_ @@ -22,7 +22,7 @@ In other words, Prometheus lets you view metrics from your different Rancher and - [Configuring Cluster Monitoring](#configuring-cluster-monitoring) - [Configuring Project Monitoring](#configuring-project-monitoring) - [Prometheus Configuration Options](#prometheus-configuration-options) - + + [Enable Node Exporter](#enable-node-exporter) + [Persistent Storage](#persistent-storage) + [Advanced Options](#advanced-options) @@ -70,13 +70,13 @@ Following Prometheus deployment, two monitoring applications are added to the cl ### Resource Consumption -When enabling cluster level monitoring, you will 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. +When enabling cluster level monitoring, you will 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. #### Prometheus Pod Resource Consumption -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. +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 +Number of Cluster Nodes | CPU (milli CPU) | Memory | Disk ------------------------|-----|--------|------ 5 | 500 | 650 MB | ~1 GB/Day 50| 2000 | 2 GB | ~5 GB/Day @@ -273,7 +273,7 @@ Some of the more important component metrics to monitor are: 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** +- **Ingress Controller Request Process Time** How fast ingress is routing connections to your cluster services. @@ -291,7 +291,7 @@ For more information about enabling logging for a cluster, see [logging]({{< bas >**Note:** Supported by [enabling cluster monitoring](#configuring-cluster-monitoring). -These metrics display the hardware utilization for a Kubernetes workload. You can also view metrics for [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) and so on. +These metrics display the hardware utilization for a Kubernetes workload. You can also view metrics for [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) and so on. To view the pod metrics, navigate into the pod view and click on **Pod Metrics**. You can also view the container metrics by navigating to **Container Metrics** option diff --git a/content/rancher/v2.x/en/tools/monitoring/expression/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/monitoring/expression/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/monitoring/expression/_index.md rename to content/rancher/v2.x/en/cluster-admin/tools/monitoring/expression/_index.md diff --git a/content/rancher/v2.x/en/cluster-admin/tools/notifiers/_index.md b/content/rancher/v2.x/en/cluster-admin/tools/notifiers/_index.md new file mode 100644 index 00000000000..5d74ae4bc99 --- /dev/null +++ b/content/rancher/v2.x/en/cluster-admin/tools/notifiers/_index.md @@ -0,0 +1,95 @@ +--- +title: Notifiers +weight: 1 +--- + +Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Notifiers are objects that you configure to leverage popular IT services, which send you notification of Rancher events. Alerts are rule sets that trigger when those notifications are sent. + +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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) and [project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) of events they need to address. + +Before you can receive [alerts]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/), you must configure one or more notifier in Rancher. + +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. + +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. + +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**: Send alert notifications to your Enterprise WeChat contacts. +
+
+ +## 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. +{{% accordion id="slack" label="Slack" %}} +1. Enter a **Name** for the notifier. +1. From Slack, create a webhook. For instructions, see the [Slack Documentation](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack). +1. From Rancher, enter your Slack webhook **URL**. +1. Enter the name of the channel that you want to send alert notifications in the following format: `#`. + + Both public and private channels are supported. +1. Click **Test**. If the test is successful, the Slack channel you're configuring for the notifier outputs `Slack setting validated`. +{{% /accordion %}} +{{% accordion id="email" label="Email" %}} +1. Enter a **Name** for the notifier. +1. In the **Sender** field, enter an email address available on your mail server that you want to send the notification. +1. In the **Host** field, enter the IP address or hostname for your SMTP server. Example: `smtp.email.com` +1. In the **Port** field, enter the port used for email. Typically, TLS uses `587` and SSL uses `465`. If you're using TLS, make sure **Use TLS** is selected. +1. Enter a **Username** and **Password** that authenticate with the SMTP server. +1. In the **Default Recipient** field, enter the email address that you want to receive the notification. +1. Click **Test**. If the test is successful, Rancher prints `settings validated` and you receive a test notification email. +{{% /accordion %}} +{{% accordion id="pagerduty" label="PagerDuty" %}} +1. Enter a **Name** for the notifier. +1. From PagerDuty, create a webhook. For instructions, see the [PagerDuty Documentation](https://support.pagerduty.com/docs/webhooks). +1. From PagerDuty, copy the webhook's **Integration Key**. +1. From Rancher, enter the key in the **Service Key** field. +1. Click **Test**. If the test is successful, your PagerDuty endpoint outputs `PageDuty setting validated`. +{{% /accordion %}} +{{% accordion id="webhook" label="WebHook" %}} +1. Enter a **Name** for the notifier. +1. Using the app of your choice, create a webhook URL. +1. Enter your webhook **URL**. +1. Click **Test**. If the test is successful, the URL you're configuring as a notifier outputs `Webhook setting validated`. +{{% /accordion %}} +{{% accordion id="WeChat" label="WeChat" %}} + +_Available as of v2.2.0_ + +1. Enter a **Name** for the notifier. +1. In the **Corporation ID** field, enter the "EnterpriseID" of your corporation, you could get it from [Profile page](https://work.weixin.qq.com/wework_admin/frame#profile). +1. From Enterprise WeChat, create an application in the [Application page](https://work.weixin.qq.com/wework_admin/frame#apps), and then enter the "AgentId" and "Secret" of this application to the **Application Agent ID** and **Application Secret** fields. +1. Select the **Recipient Type** and then enter a corresponding id to **Default Recipient** field, for example, 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). +{{% /accordion %}} + +1. Click **Add** to complete adding the notifier. + +**Result:** Your notifier is added to Rancher. + +## What's Next? + +After creating a notifier, set up alerts to receive notifications of Rancher system events. + +- [Cluster owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) can set up alerts at the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/cluster-alerts). +- [Project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) can set up alerts at the [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/alerts/project-alerts). +
+
+ +## 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. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/_index.md similarity index 99% rename from content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md rename to content/rancher/v2.x/en/cluster-admin/volumes-and-storage/_index.md index fd0a3644f5d..90c22786be7 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/_index.md @@ -1,9 +1,10 @@ --- title: Volumes and Storage -weight: 3050 +weight: 2031 aliases: - /rancher/v2.x/en/concepts/volumes-and-storage/ - /rancher/v2.x/en/tasks/clusters/adding-storage/ + - /rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/ --- When deploying an application that needs to retain data, you'll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application's pod fails. @@ -165,7 +166,7 @@ _Storage Classes_ allow you to dynamically provision persistent volumes on deman ## iSCSI Volumes With Rancher Launched Kubernetes Clusters -In [Rancher Launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes. +In [Rancher Launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes. Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the [iSCSI initiator tool](http://www.open-iscsi.com/), which is embedded in the kubelet's `rancher/hyperkube` Docker image. From each kubelet (i.e., the _initiator_), the tool discovers and launches sessions with an iSCSI volume (i.e., the _target_). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/_index.md similarity index 91% rename from content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/_index.md rename to content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/_index.md index 2b054ef2223..895e45a11ef 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/_index.md @@ -3,6 +3,7 @@ title: Provisioning Storage Examples weight: 3053 aliases: - /rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/ + - /rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/ --- Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/nfs/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/nfs/_index.md similarity index 97% rename from content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/nfs/_index.md rename to content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/nfs/_index.md index e56839881f9..6383ba367f3 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/nfs/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/nfs/_index.md @@ -3,6 +3,7 @@ title: NFS Storage weight: 3054 aliases: - /rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/nfs/ + - /rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/nfs/ --- Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/vsphere/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/vsphere/_index.md similarity index 97% rename from content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/vsphere/_index.md rename to content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/vsphere/_index.md index dc1e0a2b180..1337546d274 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/vsphere/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/vsphere/_index.md @@ -3,6 +3,7 @@ title: vSphere Storage weight: 3055 aliases: - /rancher/v2.x/en/tasks/clusters/adding-storage/provisioning-storage/vsphere/ + - /rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/vsphere/ --- To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume [storage class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes). This practice dynamically provisions vSphere storage when workloads request volumes through a [persistent volume claim]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/). @@ -19,12 +20,12 @@ In order to provision vSphere volumes in a cluster created with the [Rancher Kub 1. From the Global view, open the cluster where you want to provide vSphere storage. 2. From the main menu, select **Storage > Storage Classes**. Then click **Add Class**. -3. Enter a **Name** for the class. +3. Enter a **Name** for the class. 4. Under **Provisioner**, select **VMWare vSphere Volume**. ![vsphere-storage-class]({{< baseurl >}}/img/rancher/vsphere-storage-class.png) -5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/storageclass.html) for details. +5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/storageclass.html) for details. 5. Click **Save**. ### Creating a Workload with a vSphere Volume diff --git a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/persistent-volume-claims/_index.md similarity index 96% rename from content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md rename to content/rancher/v2.x/en/cluster-admin/volumes-and-storage/persistent-volume-claims/_index.md index 46f28a147e7..7845b93cd3b 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/persistent-volume-claims/_index.md @@ -3,6 +3,7 @@ title: Persistent Volume Claims weight: 3052 aliases: - /rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim + - /rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/examples/persistent-volume-claims/ --- _Persistent Volume Claims_ (or PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. When you create a deployment, you should usually attach a PVC so that your application can lay claim to persistent storage. This claim lets your deployment application store its data in an external location, so that if one of the application's containers fails, it can be replaced with a new container and continue accessing its data stored externally, as though an outage never occurred. diff --git a/content/rancher/v2.x/en/admin-settings/agent-options/_index.md b/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md similarity index 98% rename from content/rancher/v2.x/en/admin-settings/agent-options/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md index 8d33d443047..aaa5212629e 100644 --- a/content/rancher/v2.x/en/admin-settings/agent-options/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md @@ -1,6 +1,9 @@ --- title: Rancher Agent Options weight: 1140 +aliases: + - /rancher/v2.x/en/admin-settings/agent-options/ + --- Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to [Create a Cluster with Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) and add the options to the generated `docker run` command when adding a node. diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md index 5665d1b8128..69f0250ac1f 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md @@ -26,5 +26,5 @@ When using Rancher to create a cluster hosted by a provider, you are prompted fo - [Creating an EKS Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/eks) - [Creating an AKS Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/aks) - [Creating an ACK Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack) -- [Creating an TKE Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke) +- [Creating a TKE Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke) - [Creating a CCE Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce) diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/_index.md index 740c166b90a..d4c3d0b0a8e 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/ack/_index.md @@ -6,7 +6,7 @@ weight: 2120 _Available as of v2.2.0_ -You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/) for ACK, but by default, this cluster driver is `inactive`. In order to launch ACK clusters, you will need to [enable the ACK cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning ACK clusters. +You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for ACK, but by default, this cluster driver is `inactive`. In order to launch ACK clusters, you will need to [enable the ACK cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning ACK clusters. ## Prerequisites diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/_index.md index 0134a01f593..db618c01bd0 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/_index.md @@ -6,7 +6,7 @@ weight: 2130 _Available as of v2.2.0_ -You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/) for CCE, but by default, this cluster driver is `inactive`. In order to launch CCE clusters, you will need to [enable the CCE cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning CCE clusters. +You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for CCE, but by default, this cluster driver is `inactive`. In order to launch CCE clusters, you will need to [enable the CCE cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning CCE clusters. ## Prerequisites in Huawei diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/_index.md index 1dc22301526..007316eedba 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/_index.md @@ -6,7 +6,7 @@ weight: 2125 _Available as of v2.2.0_ -You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/) for TKE, but by default, this cluster driver is `inactive`. In order to launch TKE clusters, you will need to [enable the TKE cluster driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning TKE clusters. +You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the [cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/) for TKE, but by default, this cluster driver is `inactive`. In order to launch TKE clusters, you will need to [enable the TKE cluster driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/cluster-drivers/#activating-deactivating-cluster-drivers). After enabling the cluster driver, you can start provisioning TKE clusters. ## Prerequisites in Tencent @@ -16,7 +16,7 @@ You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE 3. Create a [Private Network and Subnet](https://intl.cloud.tencent.com/document/product/215/4927) in the region that you want to deploy your Kubernetes cluster. -4. Create a [SSH key pair](https://intl.cloud.tencent.com/document/product/213/6092). This key is used to access the nodes in the Kubernetes cluster. +4. Create a [SSH key pair](https://intl.cloud.tencent.com/document/product/213/6092). This key is used to access the nodes in the Kubernetes cluster. ## Create a TKE Cluster diff --git a/content/rancher/v2.x/en/cluster-provisioning/production/_index.md b/content/rancher/v2.x/en/cluster-provisioning/production/_index.md index 4c05895ede2..7711b93834d 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/production/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/production/_index.md @@ -1,6 +1,6 @@ --- title: Production Ready Cluster -weight: 2510 +weight: 2005 --- While Rancher makes it easy to create Kubernetes clusters, a production ready cluster takes more consideration and planning. There are three roles that can be assigned to nodes: `etcd`, `controlplane` and `worker`. In the next sections each of the roles will be described in more detail. diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md index 54a1e5fb32d..dbbd556addb 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md @@ -19,4 +19,4 @@ After you create a node template in Rancher, it's saved so that you can use this ## Node Drivers -If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/node-drivers/#activating-deactivating-node-drivers), or you can [add your own custom node driver]({{< baseurl >}}/rancher/v2.x/en/tools/drivers/node-drivers/#adding-custom-node-drivers). +If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#activating-deactivating-node-drivers), or you can [add your own custom node driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#adding-custom-node-drivers). diff --git a/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md b/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md index 4b550200634..bf50909cc44 100644 --- a/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/air-gap-single-node/install-rancher/_index.md @@ -11,7 +11,7 @@ For security purposes, SSL (Secure Sockets Layer) is required when using Rancher >**Do you want to...** > >- Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{< baseurl >}}/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/). ->- Record all transactions with the Rancher API? See [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#enable-api-audit-log). +>- Record all transactions with the Rancher API? See [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#api-audit-log). Choose from the following options: @@ -91,4 +91,4 @@ docker run -d --restart=unless-stopped \ {{% /accordion %}} -### [Next: Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/) \ No newline at end of file +### [Next: Configure Rancher for the Private Registry]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/) diff --git a/content/rancher/v2.x/en/installation/arm64-platform/_index.md b/content/rancher/v2.x/en/installation/arm64-platform/_index.md deleted file mode 100644 index 02fd9660303..00000000000 --- a/content/rancher/v2.x/en/installation/arm64-platform/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Running on ARM64 (Experimental) -weight: 7600 ---- - -_Available as of v2.2.0_ - -> **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 [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/) -- Create custom cluster and adding ARM64 based node(s) - - Kubernetes cluster version must be 1.12 or higher - - CNI Network Provider must be [Flannel]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/#flannel) -- Importing clusters that contain ARM64 based nodes - - Kubernetes cluster version must be 1.12 or higher - -Please see [Cluster Options]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/) how to configure the cluster options. - -The following features are not tested: - -* Monitoring, alerts, notifiers, pipelines and logging -* Launching apps from the catalog diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md index 2ca64e4b31f..b7e97f2c4ce 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md @@ -166,7 +166,7 @@ Rancher will respond `200` to health checks on the `/healthz` endpoint. 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/). + >**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 occurences of `FQDN` to the DNS name for Rancher. diff --git a/content/rancher/v2.x/en/installation/options/_index.md b/content/rancher/v2.x/en/installation/options/_index.md new file mode 100644 index 00000000000..9f9b09f0596 --- /dev/null +++ b/content/rancher/v2.x/en/installation/options/_index.md @@ -0,0 +1,12 @@ +--- +title: Advanced Options +weight: 350 +--- + +When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options: + +| Advanced Option | Available as of | +| --- | ---| +| [Custom CA Certificate]({{< baseurl >}}/rancher/v2.x/en/installation/options/options/) | v2.0.0 | +| [API Audit Log]({{< baseurl >}}/rancher/v2.x/en/installation/options/api-audit-log/) | v2.0.0 | +| [TLS Settings]({{< baseurl >}}/rancher/v2.x/en/installation/options/tls-settings/) | v2.1.7 | diff --git a/content/rancher/v2.x/en/admin-settings/api-audit-log/_index.md b/content/rancher/v2.x/en/installation/options/api-audit-log/_index.md similarity index 98% rename from content/rancher/v2.x/en/admin-settings/api-audit-log/_index.md rename to content/rancher/v2.x/en/installation/options/api-audit-log/_index.md index 48876644434..7fe798eb7ed 100644 --- a/content/rancher/v2.x/en/admin-settings/api-audit-log/_index.md +++ b/content/rancher/v2.x/en/installation/options/api-audit-log/_index.md @@ -2,7 +2,8 @@ title: API Audit Log weight: 10000 aliases: -- /rancher/v2.x/en/installation/api-auditing + - /rancher/v2.x/en/installation/api-auditing/ + - /rancher/v2.x/en/admin-settings/api-auditing/ --- 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. @@ -13,9 +14,9 @@ You can enable API Auditing during Rancher installation or upgrade. The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation. -- [Single Node Install - Enable API Audit Log]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#enable-api-audit-log) +- [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#api-audit-log) -- [HA Install - Enable API Audit Log]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#enable-api-audit-log) +- [HA Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#api-audit-log) ## API Audit Log Options @@ -23,7 +24,7 @@ The usage below defines rules about what the audit log should record and what da Parameter | Description | ---------|----------| - `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value.

See [Audit Level Logging](#audit-level-logging) for a table that displays what each setting logs. | + `AUDIT_LEVEL` | `0` - Disable audit log (default setting).
`1` - Log event metadata.
`2` - Log event metadata and request body.
`3` - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same `auditID` value.

See [Audit Level Logging](#audit-level-logging) for a table that displays what each setting logs. | `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host.

Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. | `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. @@ -594,4 +595,4 @@ The code sample below depicts an API response, with both its metadata header and } } } -``` \ No newline at end of file +``` diff --git a/content/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/_index.md b/content/rancher/v2.x/en/installation/options/custom-ca-root-certificate/_index.md similarity index 52% rename from content/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/_index.md rename to content/rancher/v2.x/en/installation/options/custom-ca-root-certificate/_index.md index e56364d1691..b4eb5525056 100644 --- a/content/rancher/v2.x/en/admin-settings/custom-ca-root-certificate/_index.md +++ b/content/rancher/v2.x/en/installation/options/custom-ca-root-certificate/_index.md @@ -1,8 +1,9 @@ --- title: Custom CA root certificate -weight: 252 +weight: 1110 aliases: - /rancher/v2.x/en/installation/custom-ca-root-certificate/ + - /rancher/v2.x/en/admin-settings/custom-ca-root-certificate/ --- If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA). @@ -16,19 +17,10 @@ Examples of services that Rancher can access: * Authentication providers * Accessing hosting/cloud API when using Node Drivers -Use the command example to start a Rancher container with your private CA certificates mounted. +## Installing with the custom CA Certificate -- The volume option (`-v`) should specify the host directory containing the CA root certificates. -- The `e` flag in combination with `SSL_CERT_DIR` declares an environment variable that specifies the mounted CA root certificates directory location inside the container. - - Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. - - Mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. +The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation. -The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. +- [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#custom-ca-certificate) -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v /host/certs:/container/certs \ - -e SSL_CERT_DIR="/container/certs" \ - rancher/rancher:latest -``` +- [HA Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#additional-trusted-cas) diff --git a/content/rancher/v2.x/en/admin-settings/tls-settings/_index.md b/content/rancher/v2.x/en/installation/options/tls-settings/_index.md similarity index 88% rename from content/rancher/v2.x/en/admin-settings/tls-settings/_index.md rename to content/rancher/v2.x/en/installation/options/tls-settings/_index.md index f5cf27f0264..589af788f27 100644 --- a/content/rancher/v2.x/en/admin-settings/tls-settings/_index.md +++ b/content/rancher/v2.x/en/installation/options/tls-settings/_index.md @@ -1,6 +1,8 @@ --- title: TLS settings weight: 11000 +aliases: + - /rancher/v2.x/en/admin-settings/tls-settings/ --- _Available as of v2.1.7_ @@ -11,9 +13,9 @@ In Rancher v2.1.7, the default TLS configuration changed to only accept TLS 1.2 The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation. -- [Single Node Install - TLS settings]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#tls-settings) +- [Single Node Install]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/#tls-settings) -- [HA Install - TLS settings]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#tls-settings) +- [HA Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#tls-settings) ## TLS settings @@ -32,5 +34,3 @@ If you need to configure TLS the same way as it was before Rancher v2.1.7, pleas |-----|-----| | `CATTLE_TLS_MIN_VERSION` | `1.0` | | `CATTLE_TLS_CIPHERS` | `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,`
`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,`
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,`
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,`
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,`
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,`
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,`
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,`
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,`
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,`
`TLS_RSA_WITH_AES_128_GCM_SHA256,`
`TLS_RSA_WITH_AES_256_GCM_SHA384,`
`TLS_RSA_WITH_AES_128_CBC_SHA,`
`TLS_RSA_WITH_AES_256_CBC_SHA,`
`TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,`
`TLS_RSA_WITH_3DES_EDE_CBC_SHA` - - diff --git a/content/rancher/v2.x/en/installation/server-tags/_index.md b/content/rancher/v2.x/en/installation/server-tags/_index.md index 785e95f2861..344865af3ca 100644 --- a/content/rancher/v2.x/en/installation/server-tags/_index.md +++ b/content/rancher/v2.x/en/installation/server-tags/_index.md @@ -1,5 +1,5 @@ --- -title: Choosing a Version of Rancher +title: Choosing a Version weight: 230 --- @@ -20,7 +20,7 @@ Tag | Description ->**Notes:** +>**Notes:** > >- The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported. >- Want to install an alpha review for preview? Install using one of the alpha tags listed on our [announcements page](https://forums.rancher.com/c/announcements) (e.g., `v2.2.0-alpha1`). diff --git a/content/rancher/v2.x/en/installation/single-node/_index.md b/content/rancher/v2.x/en/installation/single-node/_index.md index 5e595fa02aa..fbd6664bc99 100644 --- a/content/rancher/v2.x/en/installation/single-node/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/_index.md @@ -116,23 +116,30 @@ After you fulfill the prerequisites, you can install Rancher using a Let's Encry ## Advanced Options -### TLS settings +When installing Rancher, there are several [advanced options]({{< baseurl >}}/rancher/v2.x/en/installation/options/) that can be enabled. -_Available as of v2.1.7_ +### Custom CA Certificate -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: +If you want to configure Rancher to use a CA root certificate to be used when validating services, you would start the Rancher container sharing the directory that contains the CA root certificate. + +Use the command example to start a Rancher container with your private CA certificates mounted. + +- The volume option (`-v`) should specify the host directory containing the CA root certificates. +- The `e` flag in combination with `SSL_CERT_DIR` declares an environment variable that specifies the mounted CA root certificates directory location inside the container. + - Passing environment variables to the Rancher container can be done using `-e KEY=VALUE` or `--env KEY=VALUE`. + - Mounting a host directory inside the container can be done using `-v host-source-directory:container-destination-directory` or `--volume host-source-directory:container-destination-directory`. + +The example below is based on having the CA root certificates in the `/host/certs` directory on the host and mounting this directory on `/container/certs` inside the Rancher container. ``` docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ - -e CATTLE_TLS_MIN_VERSION="1.0" \ + -v /host/certs:/container/certs \ + -e SSL_CERT_DIR="/container/certs" \ rancher/rancher:latest ``` -See [TLS settings]({{< baseurl >}}/rancher/v2.x/en/admin-settings/tls-settings) for more information and options. - - -### Enable API Audit Log +### API Audit Log The API Audit Log records all the user and system transactions made through Rancher server. @@ -148,6 +155,21 @@ docker run -d --restart=unless-stopped \ rancher/rancher:latest ``` +### TLS settings + +_Available as of v2.1.7_ + +To set a different TLS configuration, you can use the `CATTLE_TLS_MIN_VERSION` and `CATTLE_TLS_CIPHERS` environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_TLS_MIN_VERSION="1.0" \ + rancher/rancher:latest +``` + +See [TLS settings]({{< baseurl >}}/rancher/v2.x/en/admin-settings/tls-settings) for more information and options. + ### Air Gap If you are visiting this page to complete an air gap installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index af469c22940..93623d655b1 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -53,7 +53,7 @@ If you elect to use a self-signed certificate to encrypt communication, you must -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \ rancher/rancher:latest ``` - + {{% /accordion %}} {{% accordion id="option-b" label="Option B-Bring Your Own Certificate: Signed by Recognized CA" %}} If your cluster is public facing, it's best to use a certificate signed by a recognized CA. @@ -72,7 +72,7 @@ If you use a certificate signed by a recognized CA, installing your certificate docker run -d --restart=unless-stopped \ -p 80:80 -p 443:443 \ rancher/rancher:latest --no-cacerts - ``` + ``` {{% /accordion %}} ## 3. Configure Load Balancer @@ -181,7 +181,86 @@ If you want to record all transactions with the Rancher API, enable the [API Aud If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. **Example:** - + + /rancher/rancher:latest + +### Persistent Data + +{{< persistentdata >}} + +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; +} +``` + +
+ +## What's Next? + +- **Recommended:** Review [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/). Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use. +- Create a Kubernetes cluster: [Provisioning Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/). + +
+ +## FAQ and Troubleshooting + +{{< ssl_faq_single >}} + +## Advanced Options + +### API Auditing + +If you want to record all transactions with the Rancher API, enable the [API Auditing]({{< baseurl >}}/rancher/v2.x/en/installation/api-auditing) feature by adding the flags below into your install command. + + -e AUDIT_LEVEL=1 \ + -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \ + -e AUDIT_LOG_MAXAGE=20 \ + -e AUDIT_LOG_MAXBACKUP=20 \ + -e AUDIT_LOG_MAXSIZE=100 \ + +### Air Gap + +If you are visiting this page to complete an [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add `` with your private registry URL in front of `rancher/rancher:latest`. + +**Example:** + /rancher/rancher:latest ### Persistent Data diff --git a/content/rancher/v2.x/en/k8s-in-rancher/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/_index.md index 6a7b31e6dbd..4bda4dc920b 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/_index.md +++ b/content/rancher/v2.x/en/k8s-in-rancher/_index.md @@ -1,5 +1,5 @@ --- -title: Kubernetes in Rancher +title: Working in Projects weight: 3000 aliases: - /rancher/v2.x/en/concepts/ diff --git a/content/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/_index.md index 8b6bd0d4c78..422bf82e033 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/_index.md +++ b/content/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/_index.md @@ -1,6 +1,6 @@ --- title: Horizontal Pod Autoscaler -weight: 2300 +weight: 3026 --- Using the Kubernetes [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) feature (HPA), you can configure your cluster to automatically scale the services it's running up or down. @@ -91,7 +91,7 @@ spec: Directive | Description ---------|----------| - `apiVersion: autoscaling/v2beta1` | The version of the Kubernetes `autoscaling` API group in use. This example manifest uses the beta version, so scaling by CPU and memory is enabled. | + `apiVersion: autoscaling/v2beta1` | The version of the Kubernetes `autoscaling` API group in use. This example manifest uses the beta version, so scaling by CPU and memory is enabled. | `name: hello-world` | Indicates that HPA is performing autoscaling for the `hello-word` deployment. | `minReplicas: 1` | Indicates that the minimum number of replicas running can't go below 1. | `maxReplicas: 10` | Indicates the maximum number of replicas in the deployment can't go above 10. @@ -165,7 +165,7 @@ For HPA to use custom metrics from Prometheus, package [k8s-prometheus-adapter]( ``` 1. Check that `prometheus-adapter` is running properly. Check the service pod and logs in the `kube-system` namespace. - + 1. Check that the service pod is `Running`. Enter the following command. ``` # kubectl get pods -n kube-system @@ -196,8 +196,8 @@ For HPA to use custom metrics from Prometheus, package [k8s-prometheus-adapter]( I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} ... {{% /accordion %}} - - + + 1. Check that the metrics API is accessible from kubectl. @@ -209,16 +209,16 @@ For HPA to use custom metrics from Prometheus, package [k8s-prometheus-adapter]( {{% accordion id="custom-metrics-api-response" label="API Response" %}} {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} {{% /accordion %}} - + - If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: `https:///k8s/clusters/`. Add the suffix `/k8s/clusters/` to API path. ``` # kubectl get --raw /k8s/clusters//apis/custom.metrics.k8s.io/v1beta1 ``` If the API is accessible, you should receive output that's similar to what follows. {{% accordion id="custom-metrics-api-response-rancher" label="API Response" %}} - {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} + {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]} {{% /accordion %}} - + ### Testing HPAs with a Service Deployment @@ -279,7 +279,7 @@ spec: app: hello-world ``` {{% /accordion %}} - + 1. Deploy it to your cluster. ``` @@ -341,7 +341,7 @@ spec: targetAverageValue: 20m ``` {{% /accordion %}} - + 1. View the HPA info and description. Confirm that metric data is shown. {{% accordion id="hpa-info-resource-metrics" label="Resource Metrics" %}} 1. Enter the following commands. @@ -399,14 +399,14 @@ spec: ``` {{% /accordion %}} - + 1. Generate a load for the service to test that your pods autoscale as intended. You can use any load-testing tool (Hey, Gatling, etc.), but we're using [Hey](https://github.com/rakyll/hey). 1. Test that pod autoscaling works as intended.

**To Test Autoscaling Using Resource Metrics:** {{% accordion id="observe-upscale-2-pods-cpu" label="Upscale to 2 Pods: CPU Usage Up to Target" %}} Use your load testing tool to to scale up to two pods based on CPU Usage. - + 1. View your HPA. ``` # kubectl describe hpa @@ -613,7 +613,7 @@ Use your load testing tool to scale up to three pods when the cpu_system usage l hello-world-54764dfbf8-5pfdr 1/1 Running 0 3m hello-world-54764dfbf8-m2hrl 1/1 Running 0 1s hello-world-54764dfbf8-q6l82 1/1 Running 0 6h - ``` + ``` {{% /accordion %}} {{% accordion id="observe-upscale-4-pods" label="Upscale to 4 Pods: CPU Usage Up to Target" %}} Use your load testing tool to upscale to four pods based on CPU usage. `horizontal-pod-autoscaler-upscale-delay` is set to three minutes by default. @@ -869,7 +869,7 @@ To do it, follow these steps: name: system:anonymous {{% /accordion %}} {{% accordion id="cluster-role-custom-resources" label="Custom Metrics: ApiGroups custom.metrics.k8s.io" %}} - + ``` apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole @@ -904,4 +904,3 @@ To do it, follow these steps: # kubectl create -f # kubectl create -f ``` - diff --git a/content/rancher/v2.x/en/k8s-in-rancher/pipelines/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/pipelines/_index.md new file mode 100644 index 00000000000..22aaaa4ada3 --- /dev/null +++ b/content/rancher/v2.x/en/k8s-in-rancher/pipelines/_index.md @@ -0,0 +1,869 @@ +--- +title: Configuring Pipelines +weight: 3065 +--- + +Configuring a pipeline automates the process of triggering and publishing builds. This section describes how to set up a pipeline in a production environment. + +- The [Basic Configuration](#basic-configuration) section provides sequential instruction on how to configure a functional pipeline. +- The [Advanced Configuration](#advanced-configuration) section provides instructions for configuring pipeline options. + +## Basic Configuration + +To configure a functional pipeline for your project, begin by completing the mandatory basic configuration steps. + +### Pipeline Configuration Outline + +Initial configuration of a pipeline in a production environment involves completion of several mandatory procedures. + +>**Note:** Before setting up a pipeline for a production environment, we recommend trying the [Pipeline Quick Start Guide]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/quick-start-guide). + + + +- [1. Configuring Version Control Providers](#1-configuring-version-control-providers) +- [2. Configuring Pipeline Stages and Steps](#2-configuring-pipeline-stages-and-steps) +- [3. Running the Pipeline](#3-running-the-pipeline) +- [4. Configuring Persistent Data for Pipeline Components](#4-configuring-persistent-data-for-pipeline-components) +- [Advanced Configuration](#advanced-configuration) + + + +### 1. Configuring Version Control Providers + +Begin configuration of your pipeline by enabling authentication with your version control provider. Rancher Pipeline supports integration with GitHub, GitLab and Bitbucket. + +Select your provider's tab below and follow the directions. + +{{% tabs %}} +{{% tab "GitHub" %}} +1. From the context menu, open the project for which you're configuring a pipeline. + +1. From the main menu, select **Tools > Pipelines**. In versions prior to v2.2.0, you can select **Resources > Pipelines**. + +1. Follow the directions displayed to **Setup a Github application**. Rancher redirects you to Github to setup an OAuth App in Github. + +1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher. + +1. If you're using GitHub for enterprise, select **Use a private github enterprise installation**. Enter the host address of your GitHub installation. + +1. Click **Authenticate**. + +{{% /tab %}} +{{% tab "GitLab" %}} + +_Available as of v2.1.0_ + +1. From the context menu, open the project for which you're configuring a pipeline. + +1. From the main menu, select **Tools > Pipelines**. In versions prior to v2.2.0, you can select **Resources > Pipelines**. + +1. Follow the directions displayed to **Setup a GitLab application**. Rancher redirects you to GitLab. + +1. From GitLab, copy the **Application ID** and **Secret**. Paste them into Rancher. + +1. If you're using GitLab for enterprise setup, select **Use a private gitlab enterprise installation**. Enter the host address of your GitLab installation. + +1. Click **Authenticate**. + +>**Note:** +> 1. Pipeline uses Gitlab [v4 API](https://docs.gitlab.com/ee/api/v3_to_v4.html) and the supported Gitlab version is 9.0+. +> 2. If you use GitLab 10.7+ and your Rancher setup is in a local network, enable the **Allow requests to the local network from hooks and services** option in GitLab admin settings. +{{% /tab %}} +{{% tab "Bitbucket Cloud" %}} + +_Available as of v2.2.0_ + +1. From the context menu, open the project for which you're configuring a pipeline. + +1. From the main menu, select **Tools > Pipelines**. + +1. Choose the **Use public Bitbucket Cloud** option. + +1. Follow the directions displayed to **Setup a Bitbucket Cloud application**. Rancher redirects you to Bitbucket to setup an OAuth consumer in Bitbucket. + +1. From Bitbucket, copy the consumer **Key** and **Secret**. Paste them into Rancher. + +1. Click **Authenticate**. + +{{% /tab %}} +{{% tab "Bitbucket Server" %}} + +_Available as of v2.2.0_ + +1. From the context menu, open the project for which you're configuring a pipeline. + +1. From the main menu, select **Tools > Pipelines**. + +1. Choose the **Use private Bitbucket Server setup** option. + +1. Follow the directions displayed to **Setup a Bitbucket Server application**. + +1. Enter the host address of your Bitbucket server installation. + +1. Click **Authenticate**. + +>**Note:** +> Bitbucket server needs to do SSL verification when sending webhooks to Rancher. Please ensure that Rancher server's certificate is trusted by the Bitbucket server. There are two options: +> +> 1. Setup Rancher server with a certificate from a trusted CA. +> 1. If you're using self-signed certificates, import Rancher server's certificate to the Bitbucket server. For instructions, see the Bitbucket server documentation for [configuring self-signed certificates](https://confluence.atlassian.com/bitbucketserver/if-you-use-self-signed-certificates-938028692.html). +> +{{% /tab %}} +{{% /tabs %}} + +**Result:** After the version control provider is authenticated, you will be automatically re-directed to start configuring which repositories that you want start using pipelines against. The list of repositories displayed are based on the user that setup the version control provider. Enable which repositories that you want to start using with a pipeline. Then click **Done**. You will be re-directed to the **Workloads > Pipelines** page and can start configuring your pipeline stages and steps. + +#### Using Self-Signed-Certificate with Version Control Providers + +If you want to use a version control provider with a certificate from a custom/internal CA root, the CA root certificates need to be added to the pipeline build pods. After configuring the version control provider, you will need to add the CA root certificate to the setting of the pipeline. + +1. Follow the instructions to [configure your version control providers](#1-configuring-version-control-providers). + +1. From the context menu, open the project for which you're configuring a pipeline. + +1. From the main menu, select **Tools > Pipelines**. + +1. Click **Edit cacerts**. + +1. Paste in the CA root certificates and click **Save cacerts**. + +**Result:** Pipelines can be used and will be able to work with the self-signed-certificate. + +### 2. Configuring Pipeline Stages and Steps + +Now that the pipeline is added to your project, you need to configure its automated stages and steps. For your convenience, there are multiple built-in step types for dedicated tasks. + +1. From your project's **Pipeline** tab, find your new pipeline, and select **Ellipsis (...) > Edit Config**. + + >**Note:** When configuring a pipeline, it takes a few moments for Rancher to check for an existing pipeline configuration. + +1. Select the **branch** you want to configure your pipeline for. + +1. If you are not configuring your pipeline using a yaml file, i.e. `.rancher-pipeline.yml`, click **Configure pipeline for this branch**. + +1. Add stages to your pipeline execution by clicking **Add Stage**. Select names for each stage of your pipeline. + +1. After the stages are created, start adding steps to each stage by clicking **Add a Step**. You can add multiple steps to each stage. + + >**Note:** As you build out each stage and step, click `Show advanced options` to make [Advanced Configurations](#advanced-configuration), such as rules to trigger or skip pipeline actions, add environment variables, or inject environment variables using secrets. Advanced options are available the pipeline, each stage, and each individual step. + + **Step types available include:** + + {{% accordion id="clone" label="Clone" %}} + +The first stage is preserved to be a cloning step that checks out source code from your repo. Rancher handles the cloning of the git repository. This action is equivalent to `git clone `. + + {{% /accordion %}} + {{% accordion id="run-script" label="Run Script" %}} + +The **Run Script** step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience you can use variables to refer to metadata of a pipeline execution. Please go to the [Pipeline Variable Reference]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/reference/#variable-substitution) for the list of available variables. + +{{% tabs %}} + +{{% tab "By UI" %}} +
+ +1. From the **Step Type** drop-down, choose **Run Script** and fill in the form. + +1. Click **Add**. + +{{% /tab %}} + +{{% tab "By YAML" %}} + +```yaml +# example +stages: +- name: Build something + steps: + - runScriptConfig: + image: golang + shellScript: go build +``` +{{% /tab %}} + +{{% /tabs %}} + +{{% /accordion %}} +{{% accordion id="build-publish-image" label="Build and Publish Images" %}} + +The **Build and Publish Image** step builds and publishes a Docker image. This process requires a Dockerfile in your source code's repository to complete successfully. + +{{% tabs %}} + +{{% tab "By UI" %}} +1. From the **Step Type** drop-down, choose **Build and Publish**. + +1. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click **Add**. + + Field | Description | + ---------|----------| + Dockerfile Path | The relative path to the Dockerfile in the source code repo. By default, this path is `./Dockerfile`, which assumes the Dockerfile is in the root directory. You can set it to other paths in different use cases (`./path/to/myDockerfile` for example). | + Image Name | The image name in `name:tag` format. The registry address is not required. For example, to build `example.com/repo/my-image:dev`, enter `repo/my-image:dev`. | + Push image to remote repository | An option to set the registry that publishes the image that's built. To use this option, enable it and choose a registry from the drop-down. If this option is disabled, the image is pushed to the internal registry. | + Build Context

(**Show advanced options**)| By default, the root directory of the source code (`.`). For more details, see the Docker [build command documentation](https://docs.docker.com/engine/reference/commandline/build/). + +{{% /tab %}} + +{{% tab "By YAML" %}} +```yaml +# example +stages: +- name: Publish Image + steps: + - publishImageConfig: + dockerfilePath: ./Dockerfile + buildContext: . + tag: repo/app:v1 + pushRemote: true + registry: example.com +``` + +You can use specific arguments for Docker daemon and the build. They are not exposed in the UI, but they are available in pipeline YAML format, as indicated in the example above. Available variables includes: + +Variable Name | Description +------------------------|------------------------------------------------------------ +PLUGIN_DRY_RUN | Disable docker push +PLUGIN_DEBUG | Docker daemon executes in debug mode +PLUGIN_MIRROR | Docker daemon registry mirror +PLUGIN_INSECURE | Docker daemon allows insecure registries +PLUGIN_BUILD_ARGS | Docker build args, a comma separated list + +{{% /tab %}} + +{{% /tabs %}} + +{{% /accordion %}} +{{% accordion id="publish-catalog-template" label="Publish Catalog Template" %}} + +_Available as of v2.2.0_ + +The **Publish Catalog Template** step publishes a version of a catalog app template (i.e. Helm chart) to a [git hosted chart repository]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/). It generates a git commit and pushes it to your chart repository. This process requires a chart folder in your source code's repository and a pre-configured secret in the dedicated pipeline namespace to complete successfully. [Pipeline variable substitution]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/reference/) is supported for any file in the chart folder. + +{{% tabs %}} + +{{% tab "By UI" %}} +
+ +1. From the **Step Type** drop-down, choose **Publish Catalog Template**. + +1. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click **Add**. + + Field | Description | + ---------|----------| + Chart Folder | The relative path to the chart folder in the source code repo, where the `Chart.yaml` file is located. | + Catalog Template Name | The name of the template. For example, wordpress. | + Catalog Template Version | The version of the template you want to publish, it should be consistent with the version defined in the `Chart.yaml` file. | + Protocol | You can choose to publish via HTTP(S) or SSH protocol. | + Secret | The secret that stores your Git credentials. You need to create a secret in dedicated pipeline namespace in the project before adding this step. If you use HTTP(S) protocol, store Git username and password in `USERNAME` and `PASSWORD` key of the secret. If you use SSH protocol, store Git deploy key in `DEPLOY_KEY` key of the secret. After the secret is created, select it in this option. | + Git URL | The Git URL of the chart repository that the template will be published to. | + Git Branch | The Git branch of the chart repository that the template will be published to. | + Author Name | The author name used in the commit message. | + Author Email | The author email used in the commit message. | + + +{{% /tab %}} + +{{% tab "By YAML" %}} + +You can add **Publish Catalog Template** steps directly in the `.rancher-pipeline.yml` file. + +Under the `steps` section, add a step with `publishCatalogConfig`. You will provide the following information: + + +* Path: The relative path to the chart folder in the source code repo, where the `Chart.yaml` file is located. +* CatalogTemplate: The name of the template. +* Version: The version of the template you want to publish, it should be consistent with the version defined in the `Chart.yaml` file. +* GitUrl: The git URL of the chart repository that the template will be published to. +* GitBranch: The git branch of the chart repository that the template will be published to. +* GitAuthor: The author name used in the commit message. +* GitEmail: The author email used in the commit message. +* Credentials: You should provide Git credentials by referencing secrets in dedicated pipeline namespace. If you publish via SSH protocol, inject your deploy key to the `DEPLOY_KEY` environment variable. If you publish via HTTP(S) protolcol, inject your username and password to `USERNAME` and `PASSWORD` environment variables. + +```yaml +# example +stages: +- name: Publish Wordpress Template + steps: + - publishCatalogConfig: + path: ./charts/wordpress/latest + catalogTemplate: wordpress + version: ${CICD_GIT_TAG} + gitUrl: git@github.com:myrepo/charts.git + gitBranch: master + gitAuthor: example-user + gitEmail: user@example.com + envFrom: + - sourceName: publish-keys + sourceKey: DEPLOY_KEY +``` +{{% /tab %}} + +{{% /tabs %}} + +{{% /accordion %}} +{{% accordion id="deploy-yaml" label="Deploy YAML" %}} + +This step deploys arbitrary Kubernetes resources to the project. This deployment requires a Kubernetes manifest file to be present in the source code repository. Pipeline variable substitution is supported in the manifest file. You can view an example file at [GitHub](https://github.com/rancher/pipeline-example-go/blob/master/deployment.yaml). For available variables, refer to [Pipeline Variable Reference]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/reference/). + +{{% tabs %}} + +{{% tab "By UI" %}} + +1. From the **Step Type** drop-down, choose **Deploy YAML** and fill in the form. + +1. Enter the **YAML Path**, which is the path to the manifest file in the source code. + +1. Click **Add**. + +{{% /tab %}} + +{{% tab "By YAML" %}} + +```yaml +# example +stages: +- name: Deploy + steps: + - applyYamlConfig: + path: ./deployment.yaml +``` + +{{% /tab %}} + +{{% /tabs %}} + +{{% /accordion %}} +{{% accordion id="deploy-catalog-app" label="Deploy Catalog App" %}} + +_Available as of v2.2.0_ + +The **Deploy Catalog App** step deploys a catalog app in the project. It will install a new app if it is not present, or upgrade an existing one. + +{{% tabs %}} + +{{% tab "By UI" %}} +
+ +1. From the **Step Type** drop-down, choose **Deploy Catalog App**. + +1. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click **Add**. + + Field | Description | + ---------|----------| + Catalog | The catalog from which the app template will be used. | + Template Name | The name of the app template. For example, wordpress. | + Template Version | The version of the app template you want to deploy. | + Namespace | The target namespace where you want to deploy the app. | + App Name | The name of the app you want to deploy. | + Answers | Key-value pairs of answers used to deploy the app. | + + +{{% /tab %}} + +{{% tab "By YAML" %}} + +You can add **Deploy Catalog App** steps directly in the `.rancher-pipeline.yml` file. + +Under the `steps` section, add a step with `applyAppConfig`. You will provide the following information: + +* CatalogTemplate: The ID of the template. This can be found by clicking `Launch app` and selecting `View details` for the app. It is the last part of the URL. +* Version: The version of the template you want to deploy. +* Answers: Key-value pairs of answers used to deploy the app. +* Name: The name of the app you want to deploy. +* TargetNamespace: The target namespace where you want to deploy the app. + +```yaml +# example +stages: +- name: Deploy App + steps: + - applyAppConfig: + catalogTemplate: cattle-global-data:library-mysql + version: 0.3.8 + answers: + persistence.enabled: "false" + name: testmysql + targetNamespace: test +``` +{{% /tab %}} + +{{% /tabs %}} + +{{% /accordion %}} +1. When you're finished adding stages and steps, click **Done.** + +### 3. Running the Pipeline + +Run your pipeline for the first time. From the **Pipeline** tab, find your pipeline and select **Ellipsis (...) > Run**. + +During this initial run, your pipeline is tested, and the following [pipeline components]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/) are deployed to your project as workloads in a new namespace dedicated to the pipeline: + +- `docker-registry` +- `jenkins` +- `minio` + +This process takes several minutes. When it completes, you can view each pipeline component from the project **Workloads** tab. + +### 4. Configuring Persistent Data for Pipeline Components + +The internal [Docker registry]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/#reg) and the [Minio]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/#minio) workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes. + +Complete both [A—Configuring Persistent Data for Docker Registry](#a—configuring-persistent-data-for-docker-registry) _and_ [B—Configuring Persistent Data for Minio](#b—configuring-persistent-data-for-minio). + +>**Prerequisites (for both parts A and B):** +> +>[Persistent volumes]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#persistent-volumes) must be available for the cluster. + +#### A. Configuring Persistent Data for Docker Registry + + +1. From the project that you're configuring a pipeline for, select the **Workloads** tab. + +1. Find the `docker-registry` workload and select **Ellipsis (...) > Edit**. + +1. Scroll to the **Volumes** section and expand it. Make one of the following selections from the **Add Volume** menu, which is near the bottom of the section: + + - **Add Volume > Add a new persistent volume (claim)** + - **Add Volume > Use an existing persistent volume (claim)** + +1. Complete the form that displays to choose a persistent volume for the internal Docker registry. +{{% tabs %}} + +{{% tab "Add a new persistent volume" %}} +
+1. Enter a **Name** for the volume claim. + +1. Select a volume claim **Source**: + + - If you select **Use a Storage Class to provision a new persistent volume**, select a [Storage Class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes) and enter a **Capacity**. + + - If you select **Use an existing persistent volume**, choose a **Persistent Volume** from the drop-down. +1. From the **Customize** section, choose the read/write access for the volume. + +1. Click **Define**. + +{{% /tab %}} + +{{% tab "Use an existing persistent volume" %}} +
+1. Enter a **Name** for the volume claim. + +1. Choose a **Persistent Volume Claim** from the drop-down. + +1. From the **Customize** section, choose the read/write access for the volume. + +1. Click **Define**. + +{{% /tab %}} + +{{% /tabs %}} + +1. From the **Mount Point** field, enter `/var/lib/registry`, which is the data storage path inside the Docker registry container. + +1. Click **Upgrade**. + +#### B. Configuring Persistent Data for Minio + + +1. From the **Workloads** tab, find the `minio` workload and select **Ellipsis (...) > Edit**. + +1. Scroll to the **Volumes** section and expand it. Make one of the following selections from the **Add Volume** menu, which is near the bottom of the section: + + - **Add Volume > Add a new persistent volume (claim)** + - **Add Volume > Use an existing persistent volume (claim)** + +1. Complete the form that displays to choose a persistent volume for the internal Docker registry. +{{% tabs %}} + +{{% tab "Add a new persistent volume" %}} +
+1. Enter a **Name** for the volume claim. + +1. Select a volume claim **Source**: + + - If you select **Use a Storage Class to provision a new persistent volume**, select a [Storage Class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes) and enter a **Capacity**. + + - If you select **Use an existing persistent volume**, choose a **Persistent Volume** from the drop-down. +1. From the **Customize** section, choose the read/write access for the volume. + +1. Click **Define**. + +{{% /tab %}} + +{{% tab "Use an existing persistent volume" %}} +
+1. Enter a **Name** for the volume claim. + +1. Choose a **Persistent Volume Claim** from the drop-down. + +1. From the **Customize** section, choose the read/write access for the volume. + +1. Click **Define**. + +{{% /tab %}} + +{{% /tabs %}} + +1. From the **Mount Point** field, enter `/data`, which is the data storage path inside the Minio container. + +1. Click **Upgrade**. + +**Result:** Persistent storage is configured for your pipeline components. + + +## Advanced Configuration + +During the process of configuring a pipeline, you can configure advanced options for triggering the pipeline or configuring environment variables. + +- [Configuring Pipeline Trigger Rules](#configuring-pipeline-trigger-rules) +- [Configuring Notifications](#configuring-notifications) +- [Configuring Timeouts](#configuring-timeouts) +- [Configuring Environment Variables](#configuring-environment-variables) +- [Configuring Pipeline Secrets](#configuring-pipeline-secrets) +- [Configuring the Executor Quota](#configuring-the-executor-quota) +- [Configuring the Compute Resources](#configuring-the-compute-resources) + +### Configuring Pipeline Trigger Rules + +When a repository is enabled, a webhook for it is automatically set in the version control system. By default, the project pipeline is triggered by a push event to a specific repository, but you can add (or change) events that trigger a build, such as a pull request or a tagging. When an event type is disabled, pipeline executions will not be triggered by the wehook of that event type. + +To change trigger rules for a repository: + +1. From the context menu, open the project for which you’ve configured a pipeline. Then select the Pipelines tab. + +1. From the pipeline for which you want to change the trigger rules, select **Ellipsis (...) > Setting**. + +1. Click on the check box to enable/disable triggering for **Push**, **Pull Request** or **Tag** event. + +1. Click **Save**. + +You can also set trigger rules to have fine-grained control of pipeline executions in pipeline configurations. Trigger rules come in two types: + +- **Run this when:** + + This type of rule starts the pipeline, stage, or step when a trigger explicitly occurs. + +- **Do Not Run this when:** + + This type of rule skips the pipeline, stage, or step when a trigger explicitly occurs. + +If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a pipeline is skipped, no execution will be triggered. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run. Wildcard character (`*`) expansion is supported in conditions. + + +{{% tabs %}} +{{% tab "Pipeline Trigger" %}} + +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Edit Config**. + +1. Click **Show advanced options**. + +1. From **Trigger Rules**, configure rules to run or skip the pipeline. + + 1. Click **Add Rule**. In the **Value** field, enter the name of the branch that triggers the pipeline. + + 1. **Optional:** Add more branches that trigger a build. + +{{% /tab %}} +{{% tab "Stage Trigger" %}} +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline for which you want to edit triggers, select **Ellipsis (...) > Edit Config**. + +1. From the pipeline stage that you want to configure a trigger for, click the **Edit** icon. + +1. Click **Show advanced options**. + +1. Add one or more trigger rules. + + 1. Click **Add Rule**. + + 1. Choose the **Type** that triggers the stage. + + | Type | Value | + | ------ | -------------------------------------------------------------------- | + | Branch | The name of the branch that triggers the stage. | + | Event | The type of event that triggers the stage (Push, Pull Request, Tag). | + +1. Click **Save**. +{{% /tab %}} +{{% tab "Step Trigger" %}} +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline for which you want to edit triggers, select **Ellipsis (...) > Edit Config**. + +1. From the pipeline step that you want to configure a trigger for, click the **Edit** icon. + +1. Click **Show advanced options**. + +1. Add one or more trigger rules. + + 1. Click **Add Rule**. + + 1. Choose the **Type** that triggers the step. + + | Type | Value | + | ------ | -------------------------------------------------------------------- | + | Branch | The name of the branch that triggers the stage. | + | Event | The type of event that triggers the stage (Push, Pull Request, Tag). | + +1. Click **Save**. +{{% /tab %}} +{{% tab "By YAML" %}} +```yaml +# example +stages: + - name: Build something + # Conditions for stages + when: + branch: master + event: [ push, pull_request ] + # Multiple steps run concurrently + steps: + - runScriptConfig: + image: busybox + shellScript: date -R + # Conditions for steps + when: + branch: [ master, dev ] + event: push +# branch conditions for the pipeline +branch: + include: [ master, feature/*] + exlclude: [ dev ] +``` +{{% /tab %}} +{{% /tabs %}} + +### Configuring Notifications + +_Available as of v2.2.0_ + +You can configure pipelines to send out notifications to any [notifiers]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#notifiers) based on the build status of a pipeline. Before configuring a notification, Rancher recommends [setting up notifiers]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#adding-notifiers) so it will be easy to add recipients immediately. + +> **Note:** Notifiers are configured at a cluster level, but pipeline notifications are configured at the project level. + +{{% tabs %}} +{{% tab "By UI" %}} +1. Find the pipline that you want to add a notification to, by opening the **Workloads** > **Pipelines** tab in your project. + +1. From the pipeline for which you want to add notifications, select **Ellipsis (...) > Edit Config**. + +1. Within the **Notification** section, turn on notifications by clicking **Enable**. + +1. Select the conditions for the notification. You can select to get a notification for the following statuses: `Failed`, `Success`, `Changed`. For example, if you want to receive notifications when an execution fails, select **Failed**. + +1. If you don't have any existing [notifiers]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#notifiers), Rancher will provide a warning that no notifers are set up and provide a link to be able to go to the notifiers page. Follow the [instructions]({{< baseurl >}}/rancher/v2.x/en/tools/notifiers-and-alerts/#adding-notifiers) to add a notifier. If you already have notifiers, you can add them to the notification by clicking the **Add Recipient** button. + +1. For each recipient, select which notifier type from the dropdown. Based on the type of notifier, you can use the default recipient or override the recipient with a different one. For example, if you have a notifier for Slack, you can update which channel to send the notification to. You can add additional notifiers by clicking **Add Recipient**. + +{{% /tab %}} +{{% tab "By YAML" %}} + +You can add notifiers directly in the `.rancher-pipeline.yml` file. + +Under the `notification` section, you will provide the following information: + + +* **Recipients:** This will be the list of notifiers/recipients that will receive the notification. + * **Notifier:** The ID of the notifier. This can be found by finding the notifier and selecting **View in API** to get the ID. + * **Recipient:** Depending on the type of the notifier, the "default recipient" can be used or you can override this with a different recipient. For example, when configuring a slack notifier, you select a channel as your default recipient, but if you wanted to send notifications to a different channel, you can select a different recipient. +* **Condition:** Select which conditions of when you want the notification to be sent. +* **Message (Optional):** If you want to change the default notification message, you can edit this in the yaml. Note: This option is not available in the UI. + +```yaml +# Example +stages: + - name: Build something + steps: + - runScriptConfig: + image: busybox + shellScript: ls +notification: + recipients: + - # Recipient + recipient: "#mychannel" + # ID of Notifier + notifier: "c-wdcsr:n-c9pg7" + - recipient: "test@example.com" + notifier: "c-wdcsr:n-lkrhd" + # Select which statuses you want the notification to be sent + condition: ["Failed", "Success", "Changed"] + # Ability to override the default message (Optional) + message: "my-message" +``` +{{% /tab %}} +{{% /tabs %}} + +### Configuring Timeouts + +Each pipeline execution has a default timeout of 60 minutes. If the pipeline execution cannot complete within its timeout period, the pipeline is aborted. If a pipeline has more executions than can be completed in 60 minutes, + +{{% tabs %}} +{{% tab "By UI" %}} +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline for which you want to edit the timeout, select **Ellipsis (...) > Edit Config**. + +1. Click **Show advanced options**. + +1. Enter a new value in the **Timeout** field. + +{{% /tab %}} +{{% tab "By YAML" %}} +```yaml +# example +stages: + - name: Build something + steps: + - runScriptConfig: + image: busybox + shellScript: ls +timeout: 30 +``` +{{% /tab %}} +{{% /tabs %}} + + +### Configuring Environment Variables + +When configuring a pipeline, you can use environment variables to configure the step's script. + +{{% tabs %}} +{{% tab "By UI" %}} +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline in which you want to use environment variables, select **Ellipsis (...) > Edit Config**. + +1. Click the **Edit** icon for the step in which you want to use environment variables. + +1. Click **Show advanced options**. + +1. Click **Add Variable**, and then enter a key and value in the fields that appear. Add more variables if needed. + +1. Edit the script, adding your environment variable(s). + +1. Click **Save**. + +{{% /tab %}} + +{{% tab "By YAML" %}} +```yaml +# example +stages: + - name: Build something + steps: + - runScriptConfig: + image: busybox + shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY} + env: + FIRST_KEY: VALUE + SECOND_KEY: VALUE2 +``` +{{% /tab %}} + +{{% /tabs %}} + +### Configuring Pipeline Secrets + +If you need to use security-sensitive information in your pipeline scripts (like a password), you can pass them in using Kubernetes [secrets]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/secrets/). + +>**Prerequisite:** Create a secret for your project for use in pipelines. + +>**Note:** Secret injection is disabled on pull request events. + +{{% tabs %}} +{{% tab "By UI" %}} +1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. + +1. From the pipeline in which you want to use environment variables, select **Ellipsis (...) > Edit Config**. + +1. Click the **Edit** icon for the step in which you want to use environment variables. + +1. Click **Show advanced options**. + +1. Click **Add From Secret**. Select the secret file that you want to use. Then choose a key. Optionally, you can enter an alias for the key. + +1. Click **Save**. + +{{% /tab %}} +{{% tab "By YAML" %}} +```yaml +# example +stages: + - name: Build something + steps: + - runScriptConfig: + image: busybox + shellScript: echo ${ALIAS_ENV} + # environment variables from project secrets + envFrom: + - sourceName: my-secret + sourceKey: secret-key + targetKey: ALIAS_ENV +``` +{{% /tab %}} +{{% /tabs %}} + +### Configuring the Executor Quota + +The _executor quota_ decides how many builds can run simultaneously in the project. If the number of triggered builds exceeds the quota, subsequent builds will queue until a vacancy opens. By default, the quota is `2`, but you can change it. + +1. From the context menu, open the project for which you've configured a pipeline. + +1. From the main menu, select **Tools > Pipelines**. + +1. From `The maximum number of pipeline executors` increment the **Scale** up or down to change the quota. A value of `0` or less removes the quota limit. + +### Configuring the Compute Resources + +When a pipeline execution is triggered, a build pod is dynamically provisioned to run your CI tasks. Under the hood, A build pod consists of one Jenkins agent container and one container for each pipeline step. You can [manage compute resources](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/) for every containers in the pod. + +To configure compute resources for Jenkins agent containers: + +1. From the context menu, open the project for which you've configured a pipeline. + +1. From the main menu, select **Tools > Pipelines**. + +1. From `Configure the resource limit and reservation for executors` edit the **Memory Reservation**, **Memory Limit**, **CPU Reservation** or **CPU Limit**, then click **Update Limit and Reservation**. + +To configure compute resources for pipeline-step containers: +{{% tabs %}} +{{% tab "By YAML" %}} + +You can configure compute resources for pipeline-step containers in the `.rancher-pipeline.yml` file. + +Under a `step` section, you will provide the following information: + +* CpuRequest: CPU request for the container of a pipeline step. +* CpuLimit: CPU limit for the container of a pipeline step. +* MemoryRequest: Memory request for the container of a pipeline step. +* MemoryLimit: Memory limit for the container of a pipeline step. + +```yaml +# example +stages: + - name: Build something + steps: + - runScriptConfig: + image: busybox + shellScript: ls + cpuRequest: 100m + cpuLimit: 1 + memoryRequest:100Mi + memoryLimit: 1Gi + - publishImageConfig: + dockerfilePath: ./Dockerfile + buildContext: . + tag: repo/app:v1 + cpuRequest: 100m + cpuLimit: 1 + memoryRequest:100Mi + memoryLimit: 1Gi +``` + +>**Note:** Rancher sets default compute resources for pipeline steps except for `Build and Publish Images` and `Run Script` steps. You can override the default value by specifying compute resources in the same way. +{{% /tab %}} +{{% /tabs %}} diff --git a/content/rancher/v2.x/en/k8s-in-rancher/recovering-etcd/_index.md b/content/rancher/v2.x/en/k8s-in-rancher/recovering-etcd/_index.md deleted file mode 100644 index 38a33c3c034..00000000000 --- a/content/rancher/v2.x/en/k8s-in-rancher/recovering-etcd/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Recovering etcd -weight: 300 ---- - -> **Note:** The ability to recovering etcd is only applicable to [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters. - -If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. Please review the best practices for the what the [number of etcd nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/production/#count-of-etcd-nodes) should be in a Kubernetes cluster. If you want to recover your set of etcd nodes, follow these instructions: - -1. Keep only one etcd node in the cluster by removing all other etcd nodes. - -2. On the single remaining etcd node, run the following command: - - ``` - $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd - ``` - - This command outputs the running command for etcd, save this command to use later. - -3. Stop the etcd container that you launched in the previous step and rename it to `etcd-old`. - - ``` - $ docker stop etcd - $ docker rename etcd etcd-old - ``` - -4. Take the saved command from Step 2 and revise it: - - - If you originally had more than 1 etcd node, then you need to change `--initial-cluster` to only contain the node that remains. - - Add `--force-new-cluster` to the end of the command. - -5. Run the revised command. - -6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a [custom cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/) and you want to reuse an old node, you are required to [clean up the nodes]({{< baseurl >}}/rancher/v2.x/en/faq/cleaning-cluster-nodes/) before attempting to add them back into a cluster. diff --git a/content/rancher/v2.x/en/project-admin/_index.md b/content/rancher/v2.x/en/project-admin/_index.md new file mode 100644 index 00000000000..3a0195bef07 --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/_index.md @@ -0,0 +1,33 @@ +--- +title: Project Administration +weight: 2500 +--- + +_Projects_ are organizational objects introduced in Rancher that ease the administrative burden of your cluster. You can use projects to support multi-tenancy. + +Projects provide an extra level of organization in your Kubernetes clusters beyond [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). In terms of hierarchy: + +- Clusters contain projects. +- Projects contain namespaces. + +Within Rancher, projects allow you to manage multiple namespaces as a single entity. In the base version of Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace! + +Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each namespace. + +You can use projects to perform actions like: + +- Assign users access to a group of namespaces (i.e., [project membership]({{< baseurl >}}/rancher/v2.x/en/project-admin/project-members)). +- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). + +### Authorization + +Non-administrative users are only authorized for project access after an administrator, cluster owner or cluster member explicitly adds them to the project's **Members** tab. + +>**Exception:** +> Non-administrative users can access projects that they create themselves. + +## Switching between Projects + +To switch between projects, use the drop-down available in the navigation bar. + +Alternatively, you can switch between projects directly in the navigation bar. Open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/_index.md b/content/rancher/v2.x/en/project-admin/editing-projects/_index.md similarity index 98% rename from content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/_index.md rename to content/rancher/v2.x/en/project-admin/editing-projects/_index.md index 122750d9d8e..f148a8df786 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/_index.md +++ b/content/rancher/v2.x/en/project-admin/editing-projects/_index.md @@ -1,8 +1,9 @@ --- title: Editing Projects -weight: 3021 +weight: 2510 aliases: - /rancher/v2.x/en/tasks/projects/create-project/ + - /rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/ --- After projects are created, there are certain aspects that can be changed later. @@ -43,7 +44,7 @@ Following project creation, you can add users as project members so that they ca > > - To add roles to the list, [Add a Custom Role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles). > - To remove roles from the list, [Lock/Unlock Roles]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/locked-roles/). - + **Result:** The chosen users are added to the project. - To revoke project membership, select the user and click **Delete**. This action deletes membership, not the user. @@ -93,22 +94,22 @@ Edit [resource quotas]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-a 1. From the main menu, select **Projects/Namespaces**. 1. Find the project that you want to add a resource quota to. From that project, select **Ellipsis (...) > Edit**. - + 1. Expand **Resource Quotas** and click **Add Quota**. Alternatively, you can edit existing quotas. - + 1. Select a [Resource Type]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#resource-quota-types). - + 1. Enter values for the **Project Limit** and the **Namespace Default Limit**. - + | Field | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------- | | Project Limit | The overall resource limit for the project. | - | Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. | - + | Namespace Default Limit | The default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit. | + 1. **Optional:** Add more quotas. 1. Click **Create**. - + **Result:** The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, Rancher won't let you save your changes. diff --git a/content/rancher/v2.x/en/project-admin/namespaces/_index.md b/content/rancher/v2.x/en/project-admin/namespaces/_index.md new file mode 100644 index 00000000000..dddbc5c7b4c --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/namespaces/_index.md @@ -0,0 +1,80 @@ +--- +title: Namespaces +weight: 2520 +--- + +Within Rancher, you can further divide projects into different [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the `default` namespace, you can use multiple namespaces to isolate applications and resources. + +Although you assign resources at the project level so that each namespace can in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace. + +Resources that you can assign directly to namespaces include: + +- [Workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/) +- [Load Balancers/Ingress]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/) +- [Service Discovery Records]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/service-discovery/) +- [Persistent Volume Claims]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/) +- [Certificates]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/) +- [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/configmaps/) +- [Registries]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/registries/) +- [Secrets]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/secrets/) + +>**Note:** Although you can assign role-based access to namespaces in the base version of Kubernetes, you cannot assign roles to namespaces in Rancher. Instead, assign role-based access at the project level. + +### Creating Namespaces + +Create a new namespace to isolate apps and resources in a project. + +>**Tip:** When working with project resources that you can assign to a namespace (i.e., [workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/), [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/configmaps), etc.) you can create a namespace on the fly. + +1. From the **Global** view, open the project where you want to create a namespace. + + >**Tip:** As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can can create them from the cluster level as well. + +1. From the main menu, select **Namespace**. The click **Add Namespace**. + +1. **Optional:** If your project has [Resource Quotas]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas) in effect, you can override the default resource **Limits** (which places a cap on the resources that the namespace can consume). + +1. Enter a **Name** and then click **Create**. + +**Result:** Your namespace is added to the project. You can begin assigning cluster resources to the namespace. + +### Moving Namespaces to Another Project + +Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application. + +1. From the **Global** view, open the cluster that contains the namespace you want to move. + +1. From the main menu, select **Projects/Namespaces**. + +1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one. + + >**Notes:** + > + >- Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking. + >- You cannot move a namespace into a project that already has a [resource quota]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/) configured. + >- If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace. + +1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**. + +**Result:** Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project. + +### Editing Namespace Resource Quotas + +If there is a [resource quota]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas) configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources. + +1. From the **Global** view, open the cluster that contains the namespace for which you want to edit the resource quota. + +1. From the main menu, select **Projects/Namespaces**. + +1. Find the namespace for which you want to edit the resource quota. Select **Ellipsis (...) > Edit**. + +1. Edit the Resource Quota **Limits**. These limits determine the resources available to the namespace. The limits must be set within the configured [project limits]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#project-limits). + + For more information about each **Resource Type**, see [Resource Quota Types]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/#resource-quota-types). + + >**Note:** + > + >- If a resource quota is not configured for the project, these options will not be available. + >- If you enter limits that exceed the configured project limits, Rancher will not let you save your edits. + +**Result:** The namespace's default resource quota is overwritten with your override. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/_index.md b/content/rancher/v2.x/en/project-admin/project-members/_index.md similarity index 90% rename from content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/_index.md rename to content/rancher/v2.x/en/project-admin/project-members/_index.md index 0be8fca75d5..386d5b80025 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/_index.md +++ b/content/rancher/v2.x/en/project-admin/project-members/_index.md @@ -1,8 +1,9 @@ --- title: Adding Users to Projects -weight: 3022 +weight: 2505 aliases: - /rancher/v2.x/en/tasks/projects/add-project-members/ + - /rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members/ --- If you want to provide a user with access and permissions to _specific_ projects and resources within a cluster, assign the user a project membership. diff --git a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/_index.md b/content/rancher/v2.x/en/project-admin/resource-quotas/_index.md similarity index 94% rename from content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/_index.md rename to content/rancher/v2.x/en/project-admin/resource-quotas/_index.md index 619ea3872a8..c5a0705b143 100644 --- a/content/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/_index.md +++ b/content/rancher/v2.x/en/project-admin/resource-quotas/_index.md @@ -1,6 +1,8 @@ --- title: Resource Quotas -weight: 5000 +weight: 2515 +aliases: + - /rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/resource-quotas/ --- _Available as of v2.1.0_ @@ -11,7 +13,7 @@ In situations where several teams share a cluster, one team may overconsume the Resource quotas in Rancher include the same functionality as the [native version of Kubernetes](https://kubernetes.io/docs/concepts/policy/resource-quotas/). However, in Rancher, resource quotas have been extended so that you can apply them to [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#projects). -In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times. +In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times. In the following diagram, a Kubernetes admin is trying to enforce a resource quota without Rancher. The admin wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (`Namespace 1-4`) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The admin has to create four different resource quotas that have the same specs configured (`Resource Quota 1-4`) and apply them individually. @@ -29,7 +31,7 @@ The resource quota includes two limits, which you set while creating or editing - **Namespace Default Limits:** - This value is the default resource limit available for each namespace. When the resource quota is set on the project level, this limit is automatically propagated to each namespace in the project. Each namespace is bound to this default limit unless you [override it](#namespace-default-limit-overrides). + This value is the default resource limit available for each namespace. When the resource quota is set on the project level, this limit is automatically propagated to each namespace in the project. Each namespace is bound to this default limit unless you [override it](#namespace-default-limit-overrides). In the following diagram, a Rancher admin wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (`Namespace 1-4`). However, in Rancher, the admin can set a resource quota for the project (`Project Resource Quota`) rather than individual namespaces. This quota includes resource limits for both the entire project (`Project Limit`) and individual namespaces (`Namespace Default Limit`). Rancher then propagates the `Namespace Default Limit` quotas to each namespace (`Namespace Resource Quota`). @@ -47,14 +49,14 @@ The following table explains the key differences between the two quota types. ## Creating Resource Quotas -You can create resource quotas in the following contexts: +You can create resource quotas in the following contexts: - [While creating projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#creating-projects) - [While editing projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/editing-projects/#editing-resource-quotas) ## Resource Quota Types -When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types. +When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types. | Resource Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -76,7 +78,7 @@ When you create a resource quota, you are configuring the pool of resources avai ## Overriding the Default Limit for a Namespace -Although the **Namespace Default Limit** propagates from the project to each namespace, in some cases, you may need to increase (or decrease) the performance for a specific namespace. In this situation, you can override the default limits by editing the namespace. +Although the **Namespace Default Limit** propagates from the project to each namespace, in some cases, you may need to increase (or decrease) the performance for a specific namespace. In this situation, you can override the default limits by editing the namespace. In the diagram below, the Rancher admin has a resource quota in effect for their project. However, the admin wants to override the namespace limits for `Namespace 3` so that it performs better. Therefore, the admin [raises the namespace limits]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#editing-namespace-resource-quotas) for `Namespace 3` so that the namespace can access more resources. @@ -85,20 +87,25 @@ In the diagram below, the Rancher admin has a resource quota in effect for their How to: [Editing Namespace Resource Quotas]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#editing-namespace-resource-quotas) +### Editing Namespace Resource Quotas + +You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources. + +For more information, see how to [edit namespace resource quotas]({{< baseurl >}}/rancher/v2.x/en/project-admin/namespaces/#editing-namespace-resource-quota/). ## Setting Container Default Resource Limit _Available as of v2.2.0_ -When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. -To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace. +To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace. When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers. > **Note:** Prior to v2.2.0, you could not launch catalog applications that did not have any limits set. With v2.2.0, you will be able to set a default container resource limit on a project and launch any catalog applications. -Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation. +Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation. | Resource Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -106,5 +113,3 @@ Once a container default resource limit is configured on a namespace, the defaul | CPU Reservation | The minimum amount of CPU (in millicores) guaranteed to the container. | | Memory Limit | The maximum amount of memory (in bytes) allocated to the container. | | Memory Reservation | The minimum amount of memory (in bytes) guaranteed to the container. - - diff --git a/content/rancher/v2.x/en/project-admin/tools/_index.md b/content/rancher/v2.x/en/project-admin/tools/_index.md new file mode 100644 index 00000000000..b9c5e61906a --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/_index.md @@ -0,0 +1,76 @@ +--- +title: Configuring Tools +weight: 2525 +--- + +Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories: + + + +- [Alerts](#alerts) +- [Logging](#logging) +- [Pipelines](#pipelines) +- [Monitoring](#monitoring) + + + +## Alerts + +To keep your clusters and applications healthy and driving your organizational productivity forward, you need stay informed of events occurring in your clusters, both planned and unplanned. To help you stay informed of these events, Rancher allows you to configure alerts. + +_Alerts_ are sets of rules, chosen by you, to monitor for specific events. The scope for alerts can be set at either the cluster or project level. + +Some examples of alert events are: + +- A Kubernetes [master component]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#kubernetes-cluster-node-components) entering an unhealthy state. +- A node or [workload]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/) error occurring. +- A scheduled deployment taking place as planned. +- A node's hardware resources becoming overstressed. + +When an event occurs, your alert is triggered, and you are sent a notification. You can then, if necessary, follow up with corrective actions. + +Additionally, 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. + +You can configure alerts at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/alerts/). + +## Logging + +Rancher can integrate with popular external services used for event streams, telemetry, or search. Rancher can integrate with the following services: + +- Elasticsearch +- splunk +- kafka +- syslog +- fluentd + +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. + +You can configure these services to collect logs at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/logging/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/logging/). + +## Pipelines + +Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline. + +To set up a pipeline, you'll first need to authorize Rancher using your GitHub settings. Directions are provided in the Rancher UI. After authorizing Rancher in GitHub, provide Rancher with a client ID and secret to authenticate. + +After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution: + +- Build your application from code to image. +- Validate your builds. +- Deploy your build images to your cluster. +- Run unit tests. +- Run regression tests. + +For more information, see [Pipelines]({{< baseurl >}}/rancher/v2.x/en/project-admin/pipelines/). + +## Monitoring + +_Available as of v2.2.0_ + +Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with [Prometheus](https://prometheus.io/), a leading open-source monitoring solution. Prometheus provides a _time series_ of your data, which is 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 let's you view metrics from your different Rancher and Kubernetes objects. Using timestamps, you can 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 and project-only Prometheus instances are also supported. + +You can configure these services to collect logs at either the [cluster level]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/) or [project level]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/monitoring/). diff --git a/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md b/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md new file mode 100644 index 00000000000..718f9c50509 --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/alerts/_index.md @@ -0,0 +1,163 @@ +--- +title: Alerts +weight: 2526 +--- + +Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Notifiers are objects that you configure to leverage popular IT services, which send you notification of Rancher events. Alerts are rule sets that trigger when those notifications are sent. + +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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) and [project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) of events they need to address. + +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. To help you stay informed of these events, you can configure alerts. + +Alerts are sets of rules, chosen by you, to monitor for specific events. The scope for alerts can be set at either the [cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/alerts/) or project level. + +At the project level, Rancher monitors specific deployments and sends alerts for: + +* Deployment availability +* Workloads status +* Pod status +* The Prometheus expression cross the thresholds +
+
+ +## Adding Project Alerts + +>**Prerequisite:** Before you can receive project alerts, you must [add a notifier]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/notifiers/#adding-notifiers). + +1. From the **Global** view, open the project that you want to configure alerts for. + +1. From the main menu, select **Tools > Alerts**. In versions prior to v2.2.0, you can choose **Resources > Alerts**. + +1. 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, complete one of the instruction subsets below. +{{% accordion id="pod" label="Pod Alerts" %}} +This alert type monitors for the status of a specific pod. + +1. Select the **Pod** option, and then select a pod from the drop-down. +1. Select a pod status that triggers an alert: + + - **Not Running** + - **Not Scheduled** + - **Restarted `` times with the last `` Minutes** + +1. Select the urgency level of the alert. The options are: + + - **Critical**: Most urgent + - **Warning**: Normal urgency + - **Info**: Least urgent + + Select the urgency level of the alert based on pod state. For example, select **Info** for Job pod which stop running after job finished. However, if an important pod isn't scheduled, it may affect operations, so choose **Critical**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="workload" label="Workload Alerts" %}} +This alert type monitors for the availability of a workload. + +1. Choose the **Workload** option. Then choose a workload from the drop-down. + +1. Choose an availability percentage using the slider. The alert is triggered when the workload's availability on your cluster nodes drops below the set percentage. + +1. Select the urgency level of the alert. + + - **Critical**: Most urgent + - **Warning**: Normal urgency + - **Info**: Least urgent + + Select the urgency level of the alert based on the percentage you choose and the importance of the workload. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="workload-selector" label="Workload Selector Alerts" %}} +This alert type monitors for the availability of all workloads marked with tags that you've specified. + +1. Select the **Workload Selector** option, and then click **Add Selector** to enter the key value pair for a label. If one of the workloads drops below your specifications, an alert is triggered. This label should be applied to one or more of your workloads. + +1. Select the urgency level of the alert. + + - **Critical**: Most urgent + - **Warning**: Normal urgency + - **Info**: Least urgent + + Select the urgency level of the alert based on the percentage you choose and the importance of the workload. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} +{{% accordion id="project-expression" label="Metric Expression Alerts" %}} +This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring. + +1. Input or select an **Expression**, the drop down shows the original metrics from Prometheus, including: + + - [**Container**](https://github.com/google/cadvisor) + - [**Kubernetes Resources**](https://github.com/kubernetes/kube-state-metrics) + - [**Customize**]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/#custom-metrics) + - [**Project Level Grafana**](http://docs.grafana.org/administration/metrics/) + - **Project Level Prometheus** + +1. 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. + +1. Input a **Threshold**, for trigger alert when the value of expression cross the threshold. + +1. Choose a **Comparison**. + +1. Select a **Duration**, for trigger alert when expression value crosses the threshold longer than the configured duration. + +1. Select the urgency level of the alert. + + - **Critical**: Most urgent + - **Warning**: Normal urgency + - **Info**: Least urgent +
+
+ Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a expression for container memory close to the limit raises above 60% deems an urgency of **Info**, but raised about 95% deems an urgency of **Critical**. + +1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. + + - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. + - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. + - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. + +{{% /accordion %}} + +1. Continue adding more **Alert Rule** to the group. + +1. Finally, choose the notifiers that send you alerts. + + - You can set up multiple notifiers. + - You can change notifier recipients on the fly. + +**Result:** Your alert is configured. A notification is sent when the alert is triggered. + +#### Managing Project Alerts + +To manage project alerts, browse to the project that alerts you want to manage. Then select **Tools > Alerts**. In versions prior to v2.2.0, you can choose **Resources > Alerts**. You can: + +- Deactivate/Reactive alerts +- Edit alert settings +- Delete unnecessary alerts +- Mute firing alerts +- Unmute muted alerts diff --git a/content/rancher/v2.x/en/project-admin/tools/logging/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/_index.md new file mode 100644 index 00000000000..12c9d60714a --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/logging/_index.md @@ -0,0 +1,57 @@ +--- +title: Logging +weight: 2527 +--- + +Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters. + +Rancher supports the following services: + +- [Elasticsearch]({{< baseurl >}}/rancher/v2.x/en/tools/logging/elasticsearch) +- [Splunk]({{< baseurl >}}/rancher/v2.x/en/tools/logging/splunk) +- [Kafka]({{< baseurl >}}/rancher/v2.x/en/tools/logging/kafka) +- [Syslog]({{< baseurl >}}/rancher/v2.x/en/tools/logging/syslog) +- [Fluentd]({{< baseurl >}}/rancher/v2.x/en/tools/logging/fluentd) + +## Requirements + +Docker daemon 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 +``` + +## Advantages + +Setting up a logging service to collect logs from your cluster/project is helpful several ways: + +- Logs errors and warnings in your Kubernetes infrastructure to a stream. The stream informs you of events like a container crashing, a pod eviction, or a node dying. +- Allows you to capture and analyze the state of your cluster and look for trends in your environment using the log stream. +- Helps you when troubleshooting or debugging. +- Saves your logs to a safe location outside of your cluster, so that you can still access them even if your cluster encounters issues. + +## Logging Scope + +You can configure logging at either cluster or project level. + +>**Note:** You can only configure one logging service per cluster or project. + +- If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + + Cluster logging writes logs for every pod in the cluster and, in [RKE clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), Kubernetes system components. Logs from the following locations are sent to your logging service: + + + - The `/var/log/containers` path for pod logging. + + - The `/var/lib/rancher/rke/logs/` path for Kubernetes system components. + +- If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + + Project logging writes logs for every pod in the project. + +After collection, all logs are stored by your logging service. Log into your service to view them. + +## Related Links + +[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/) diff --git a/content/rancher/v2.x/en/tools/logging/custom/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/custom/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/logging/custom/_index.md rename to content/rancher/v2.x/en/project-admin/tools/logging/custom/_index.md diff --git a/content/rancher/v2.x/en/tools/logging/elasticsearch/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/elasticsearch/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/logging/elasticsearch/_index.md rename to content/rancher/v2.x/en/project-admin/tools/logging/elasticsearch/_index.md diff --git a/content/rancher/v2.x/en/tools/logging/fluentd/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/fluentd/_index.md old mode 100755 new mode 100644 similarity index 100% rename from content/rancher/v2.x/en/tools/logging/fluentd/_index.md rename to content/rancher/v2.x/en/project-admin/tools/logging/fluentd/_index.md diff --git a/content/rancher/v2.x/en/tools/logging/kafka/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/kafka/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/logging/kafka/_index.md rename to content/rancher/v2.x/en/project-admin/tools/logging/kafka/_index.md diff --git a/content/rancher/v2.x/en/project-admin/tools/logging/splunk/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/splunk/_index.md new file mode 100644 index 00000000000..1ded1cc0fac --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/logging/splunk/_index.md @@ -0,0 +1,102 @@ +--- +title: Splunk +weight: 300 +--- + +If your organization uses [Splunk](https://www.splunk.com/), you can configure Rancher to send it cluster or project logs. Afterwards logs are sent, you can use Splunk to view them. + +## Configuring Splunk Logging + +You can configure Rancher to send Kubernetes logs to your instance of Splunk. + +>**Prerequisites:** +> +>- Configure HTTP event collection for your Splunk Server (Splunk Enterprise or Splunk Cloud). +>- Enable all tokens, and then create a new token. +> +>For more information, see [Splunk Documentation](http://docs.splunk.com/Documentation/Splunk/7.1.2/Data/UsetheHTTPEventCollector#About_Event_Collector_tokens). + +1. Browse to the cluster or project that you want to log. +{{% accordion id="cluster" label="To Configure Cluster Logging:" %}} +If you're a [cluster owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) who works in operations or security, configure cluster logging. + +1. From the **Global** view, open the cluster that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. +{{% /accordion %}} +{{% accordion id="project" label="To Configure Project Logging:" %}} +If you're a [project owner or member]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) who works on an application, configure project logging. + +1. From the **Global** view, open the project that you want to configure logging for. + +1. From the main menu, select **Tools > Logging**. In versions prior to v2.2.0, you can choose **Resources > Logging**. +{{% /accordion %}} + +1. Select **Splunk**. + +1. Complete the **Splunk HTTP Event Collector Configuration** form. + + 1. From 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. From the **Source** field, enter the name of the token as entered in Splunk. + + 1. **Optional:** Enter one or more [index](http://docs.splunk.com/Documentation/Splunk/7.1.2/Indexer/Aboutindexesandindexers) that's allowed for your token. + +1. If your Splunk is using SSL, you need to complete the **SSL Configuration** form. + + 1. Enter the private key and client certificate. You can either copy and paste them or upload them by **Read from a file**. + + 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 private key password. + + 1. If you are using a self-signed certificate, you need to select the **Enabled - Input trusted server certificate** option and enter your **CA Certificate PEM**. + +1. 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 event 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 Splunk. + +1. Click **Save**. + +**Result:** Rancher is now configured to send logs to Splunk. Log into your Splunk instance to view events for your cluster and containers. + +## 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. + ![View Logs]({{< baseurl >}}/img/rancher/splunk/splunk4.jpg) + +1. To view the actual logs, click on the source that you declared earlier. + ![View Logs]({{< baseurl >}}/img/rancher/splunk/splunk5.jpg) + +## 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. diff --git a/content/rancher/v2.x/en/tools/logging/syslog/_index.md b/content/rancher/v2.x/en/project-admin/tools/logging/syslog/_index.md similarity index 100% rename from content/rancher/v2.x/en/tools/logging/syslog/_index.md rename to content/rancher/v2.x/en/project-admin/tools/logging/syslog/_index.md diff --git a/content/rancher/v2.x/en/project-admin/tools/monitoring/_index.md b/content/rancher/v2.x/en/project-admin/tools/monitoring/_index.md new file mode 100644 index 00000000000..67c80cdb818 --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/monitoring/_index.md @@ -0,0 +1,308 @@ +--- +title: Monitoring +weight: 2528 +--- + +_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. Prometheus provides a _time series_ of your data, which is, according to [Prometheus documentation](https://prometheus.io/docs/concepts/data_model/): + +>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 and project-only Prometheus instances are also supported. + +## In This Document + + + +- [Monitoring Scope](#monitoring-scope) + + + [Cluster Monitoring](#cluster-monitoring) + + [Project Monitoring](#project-monitoring) +- [Configuring Cluster Monitoring](#configuring-cluster-monitoring) +- [Configuring Project Monitoring](#configuring-project-monitoring) +- [Prometheus Configuration Options](#prometheus-configuration-options) + + + [Enable Node Exporter](#enable-node-exporter) + + [Persistent Storage](#persistent-storage) + + [Advanced Options](#advanced-options) +- [Viewing Metrics](#viewing-metrics) + + + [Rancher Dashboard](#rancher-dashboard) + + [Available Dashboard](#available-dashboard) + + [Grafana](#grafana) +- [Cluster Metrics](#cluster-metrics) +- [Etcd Metrics](#etcd-metrics) +- [Kubernetes Components Metrics](#kubernetes-components-metrics) +- [Rancher Logging Metrics](#rancher-logging-metrics) +- [Workload Metrics](#workload-metrics) +- [Custom Metrics](#custom-metrics) + + + +## Monitoring Scope + +Using Prometheus, you can monitor Rancher at both the cluster and project level. Rancher deploys an individual Prometheus server per cluster, and an additional Prometheus server per Rancher project for multi-tenancy. + +[Cluster monitoring](#cluster-monitoring) allows you to view the health of a cluster's Kubernetes control plane and individual nodes. System administrators will likely be more interested in cluster monitoring, as administrators are more invested in the health of the Rancher control plane and cluster nodes. + +[Project monitoring](#project-monitoring) lets you view the state of pods running in a given project. Users responsible for maintaining a project will be most interested in project monitoring, as it helps them keep their applications up and running for their users. + +### Cluster Monitoring + +When you enable monitoring for one of your Rancher clusters, Prometheus collects metrics from the cluster components below, which you can view in graphs and charts. We'll have more about the specific metrics collected later in this document. + +- [Kubernetes control plane](#kubernetes-components-metrics) +- [etcd database](#etcd-metrics) +- [All nodes (including workers)](#cluster-metrics) + +### Project Monitoring + +When you enable monitoring for a Rancher project, Prometheus collects metrics from its deployed HTTP and TCP/UDP workloads. We'll have more about the specific metrics collected [later in this document](#custom-metrics). + +## Configuring Cluster Monitoring + +You can deploy Prometheus monitoring for a cluster, navigate to **Tools > Monitoring** as shown in the GIF below, which displays a user enabling cluster monitoring for a cluster named `local`. The only required action for deployment is to select the **Enable** option and click **Save**, but you might want to [customize configuration options](#prometheus-configuration-options) for your environment. + +![EnableClusterMonitoring]({{< baseurl >}}/img/rancher/enable-cluster-monitoring.gif) + +Following Prometheus deployment, two monitoring applications are added to the cluster's `system` project's **Apps** page: `cluster-monitoring` and `monitoring-operator`. You can use the `cluster-monitoring` catalog app to [access the Grafana instance](#grafana-accessing-for-clusters) for the cluster. + +### Resource Consumption + +When enabling cluster level monitoring, you will 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. + +#### Prometheus Pod Resource Consumption + +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 + +#### Other Pods Resource Consumption + +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 + +## Configuring Project Monitoring + +You can enable project monitoring by opening the project and then selecting **Tools > Monitoring** as shown in the GIF below, which displays enabling the `default` project monitoring. + +![EnableProjectMonitoring]({{< baseurl >}}/img/rancher/enable-project-monitoring.gif) + +After you enable project monitoring, a single application is added to the project's **Apps** page: `project-monitoring`. Use this catalog app to [access the Grafana instance](#grafana-accessing-for-projects) for the project. + +With enabling cluster monitoring, you can collect the [Workload metrics](#workload-metrics) for this project, otherwise, you can only collect the [Custom metrics](#custom-metrics) from this project. + +## Prometheus Configuration Options + +While configuring monitoring at either the cluster or project level, you can choose options to customize your monitoring settings. You can enable the options below while completing either [Configuring Cluster Monitoring](#configuring-cluster-monitoring) or [Configuring Project Monitoring](#configuring-project-monitoring). + +Option | Description +-------|------------- +Data Retention | Configures how long your Prometheus instance retains monitoring data scraped from Rancher objects before it's purged. +Enable Node Exporter | Configures using [Node Exporter](https://github.com/prometheus/node_exporter/blob/master/README.md) or not, please take a look at the [notes](#enable-node-exporter). +Node Exporter Host Port | Configures the host port on which [Node Exporter](https://github.com/prometheus/node_exporter/blob/master/README.md) data is exposed (i.e., data that Prometheus collects from your node hardware), if enabling Node Exporter. +Enable Persistent Storage for Prometheus | Lets you configure storage for Prometheus so that you can retain your metric data if your Prometheus pod fails. See [Persistent Storage](#persistent-storage). +Enable Persistent Storage for Grafana | Lets you configure storage so that you can retain your dashboards and configuration if your Grafana pod fails. See [Persistent Storage](#persistent-storage). +Prometheus CPU Limit | Configures [the CPU resource limits](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) of the Promehtues pod. +Prometheus CPU Reservation | Configures [the CPU resource requests](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu) of the Promehtues pod. +Prometheus Memory Limit | Configures [the Memory resource limits](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) of the Promehtues pod. +Prometheus Memory Reservation | Configures [the Memory resource requests](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory) of the Promehtues pod. +Add Selector | If you want to deploy the Prometheus/Grafana pods to a specific node when enable monitoring, add selectors to the pods so that they're deployed to your selected node(s). To use this option, you must first apply labels to your nodes. + +### Enable Node Exporter + +Node Exporter is a popular open source exporter which can expose the metrics for hardware and \*NIX kernels OS, it is designed to monitor the host system. However, there are still namespacing issues with running it in a container, mostly around filesystem mount spaces. So if we need to monitor the actual network stats for the container network, we must deploy it with `hostNetwork` mode. + +Firstly, you need to consider which host port should expose to avoid port conflicts and fill into `Node Exporter Host Port` field. Secondly, you must open that port to allow the internal traffic from `Prometheus`. + +### Persistent Storage + +>**Prerequisite:** Configure one or more [storage class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#adding-storage-classes) to use as [persistent storage]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/) for your Prometheus/Grafana instance. + +By default, when you enable Prometheus for either a cluster or project, all monitoring data that Prometheus collects is stored on its own pod. This local storage means that if your Prometheus/Grafana pods fail, you'll lose all your monitoring data. Therefore, we recommend configuring persistent storage external to your cluster. This way, if your Prometheus/Grafana pods fail, the new pods that replace them can recover using your persistent storage. + +You can configure persistent storage for Prometheus and/or Grafana by using the radio buttons available when completing either [Configuring Cluster Monitoring](#configuring-cluster-monitoring) or [Configuring Project Monitoring](#configuring-project-monitoring). After enabling persistent storage, you'll then need to specify a [storage class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes) that's used to provision a [persistent volume]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#persistent-volumes), along with the size of the volume that's being provisioned. + +### Advanced Options + +>**Warning:** Monitoring app is [a specially designed app](https://github.com/rancher/system-charts/tree/dev/charts/rancher-monitoring). Any modification without familiarizing the entire app can lead to catastrophic errors. + +Monitoring is driven by [Rancher Catalog App]({{< baseurl >}}/rancher/v2.x/en/catalog), so you can expand all options by clicking the **Show advanced options** and then configure it as you wolud configure any other app. + +## Viewing Metrics + +After you've deployed Prometheus to a cluster or project, you can view that data in one of two places: + +- [Rancher Dashboard](#cluster-dashboard) +- [Grafana](#grafana) + +### Rancher Dashboard + +After enabling cluster monitoring to one of your clusters, you can view the data it collects from the Rancher Dashboard. + +>**Note:** The Rancher Dashboard only displays Prometheus analytics for the cluster, not individual projects. If you want to view analytics for a project, you must [access the project's Grafana instance](#grafana-accessing-for-projects). + +#### Rancher Dashboard Use + +Prometheus metrics are displayed below the main dashboard display, and are denoted with the Grafana icon as displayed below. + +>**Tip:** Click the icon to open the metrics in [Grafana](#grafana). + +In each Prometheus metrics widget, you can toggle between a **Detail** view, which displays graphs and charts that let you view each event in a Prometheus time series, or a **Summary** view, which only lists events in a Prometheus time series out of the norm. + +You can also change the range of the time series that you're viewing to see a more refined or expansive data sample. + +Finally, you can customize the data sample to display data between chosen dates and times. + +### Available Dashboard + +After deploying Prometheus to a cluster, you can view the metrics from its Dashboard. + +When analyzing 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 (i.e., 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. + +### Grafana + +Your other option for viewing cluster data is Grafana, which is a leading open source platform for analytics and monitoring. + +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). + +#### Accessing Grafana + +When enable monitoring, Rancher automatically creates a link to Grafana instance. Use this link to view monitoring data for the cluster or project. + +##### Grafana and Authentication + +When you deploy Prometheus to a cluster or project, Rancher automatically creates a Grafana instance for the object. Rancher determines which users can access the new Grafana instance, as well as the objects they can view within it, by validating them against cluster or project membership. Users that hold membership for the object will be able to access its Grafana instance. In other words, users' access in Grafana mirrors their access in Rancher. + +##### Grafana: Accessing for Clusters + +To access an instance of Grafana displays monitoring analytics for a cluster, browse to the cluster's `system` project and open **Apps**. From the `cluster-monitoring` catalog app, click the `/index.html` link. To view data for your cluster navigate to the cluster's _system_ project. + +##### Grafana: Accessing for Projects + +To access an instance of Grafana that's monitoring a project, browse to the applicable cluster and project. Then open **Apps**. From the `project-monitoring` catalog app, click the `/index.html` link. + +#### Manage Grafana + +To manage your cluster or project Grafana, you can sign into it by using `admin/admin`. For security, you should change the default password after first login. + +The preset Grafana dashboards are imported via [Grafana provisioning mechanism](http://docs.grafana.org/administration/provisioning/#dashboards), so you cannot modify them directly. A workaround, for now, is to clone the original and then modify the new copy. + +## Cluster Metrics + +These metrics display the hardware utilization for all nodes in your cluster, regardless of its Kubernetes 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. + +To view the data for one node, browse into the **Nodes** and go into a node view to look for the **Node Metrics**. + +[_Get expressions for Cluster Metrics_]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/expression/#cluster-metrics) + +## Etcd Metrics + +>**Note:** Supported in [the cluster launched by Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters). + +These 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 leadership 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 leadership 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_]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/expression/#etcd-metrics) + +## Kubernetes Components Metrics + +These 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 in [the cluster launched by Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters). + +When analyzing Kubernetes component metrics, don't be concerned about any single standalone metric in the charts and graphs that display. Rather, you should establish a baseline for metrics considered normal following a period of observation (i.e., 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_]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/expression/#kubernetes-component-metrics) + +## Rancher Logging Metrics + +Although the Dashboard for a cluster primary displays data sourced from Prometheus, it also displays information for cluster logging, provided that you have configured Rancher to use a logging service. + +For more information about enabling logging for a cluster, see [logging]({{< baseurl >}}/rancher/v2.x/en/tools/logging). + +[_Get expressions for Rancher Logging Metrics_]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/expression/#rancher-logging-metrics) + +## Workload Metrics + +>**Note:** Supported by [enabling cluster monitoring](#configuring-cluster-monitoring). + +These metrics display the hardware utilization for a Kubernetes workload. You can also view metrics for [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) and so on. + +To view the pod metrics, navigate into the pod view and click on **Pod Metrics**. You can also view the container metrics by navigating to **Container Metrics** option + +[_Get expressions for Workload Metrics_]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/expression/#workload-metrics) + +## Custom Metrics + +>**Note:** Supported by [enabling project monitoring](#configuring-project-monitoring). + +If you want to scrape the metrics from any [exporters](https://prometheus.io/docs/instrumenting/exporters/), you only need to set up some exposing endpoints on deploying but without configuring the project Prometheus directly. + +Imagine that you have deployed a [Redis](https://redis.io/) app/cluster in the namespace `redis-app` of the project `Datacenter`, and you are going to monitor it via [Redis exporter](https://github.com/oliver006/redis_exporter). By enabling project monitoring, you only need to configure **Custom Metrics** under **Advanced Options** as shown in the GIF below, and set the correct `Container Port`, `Path` and `Protocol`. + +![AddCustomMetrics]({{< baseurl >}}/img/rancher/add-custom-metrics.gif) diff --git a/content/rancher/v2.x/en/project-admin/tools/monitoring/expression/_index.md b/content/rancher/v2.x/en/project-admin/tools/monitoring/expression/_index.md new file mode 100644 index 00000000000..1cccdf62887 --- /dev/null +++ b/content/rancher/v2.x/en/project-admin/tools/monitoring/expression/_index.md @@ -0,0 +1,379 @@ +--- +title: Expression +weight: 10000 +--- + +## In This Document + + + +- [Cluster Metrics](#cluster-metrics) + + + [Node Metrics](#node-metrics) +- [Etcd Metrics](#etcd-metrics) +- [Kubernetes Components Metrics](#kubernetes-components-metrics) +- [Rancher Logging Metrics](#rancher-logging-metrics) +- [Workload Metrics](#workload-metrics) + + + [Pod Metrics](#pod-metrics) + + [Container Metrics](#container-metrics) + + + +## Cluster Metrics + +- **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])))` | + +- **Load Average** + + | Catalog | Expression | + | --- | --- | + | Detail |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)`
| + | Summary |
load1`sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load5`sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})`
load15`sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})`
| + +- **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)` | + +- **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"})` | + +- **Disk I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
read`sum(rate(node_disk_read_bytes_total[5m])) by (instance)`
written`sum(rate(node_disk_written_bytes_total[5m])) by (instance)`
| + | Summary |
read`sum(rate(node_disk_read_bytes_total[5m]))`
written`sum(rate(node_disk_written_bytes_total[5m]))`
| + +- **Network Packets** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| + | Summary |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +- **Network I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
| + | Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
| + +### Node Metrics + +- **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])))` | + +- **Load Average** + + | Catalog | Expression | + | --- | --- | + | Detail |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| + | Summary |
load1`sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load5`sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
load15`sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})`
| + +- **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"}) ` | + +- **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"})` | + +- **Disk I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| + | Summary |
read`sum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))`
written`sum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))`
| + +- **Network Packets** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| + | Summary |
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +- **Network I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
| + | Summary |
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
| + +## Etcd Metrics + +- **Etcd has a leader** + + `max(etcd_server_has_leader)` + +- **Number of 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 |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)`
| + | Summary |
in`sum(rate(etcd_network_client_grpc_received_bytes_total[5m]))`
out`sum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))`
| + +- **Peer Traffic** + + | Catalog | Expression | + | --- | --- | + | Detail |
in`sum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)`
| + | Summary |
in`sum(rate(etcd_network_peer_received_bytes_total[5m]))`
out`sum(rate(etcd_network_peer_sent_bytes_total[5m]))`
| + +- **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 |
lease-watch`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)`
watch`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)`
| + | Summary |
lease-watch`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"})`
watch`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"})`
| + +- **Raft Proposals** + + | Catalog | Expression | + | --- | --- | + | Detail |
applied`sum(increase(etcd_server_proposals_applied_total[5m])) by (instance)`
committed`sum(increase(etcd_server_proposals_committed_total[5m])) by (instance)`
pending`sum(increase(etcd_server_proposals_pending[5m])) by (instance)`
failed`sum(increase(etcd_server_proposals_failed_total[5m])) by (instance)`
| + | Summary |
applied`sum(increase(etcd_server_proposals_applied_total[5m]))`
committed`sum(increase(etcd_server_proposals_committed_total[5m]))`
pending`sum(increase(etcd_server_proposals_pending[5m]))`
failed`sum(increase(etcd_server_proposals_failed_total[5m]))`
| + +- **RPC Rate** + + | Catalog | Expression | + | --- | --- | + | Detail |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)`
| + | Summary |
total`sum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))`
fail`sum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))`
| + +- **Disk Operations** + + | Catalog | Expression | + | --- | --- | + | Detail |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)`
| + | Summary |
commit-called-by-backend`sum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))`
fsync-called-by-wal`sum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))`
| + +- **Disk Sync Duration** + + | Catalog | Expression | + | --- | --- | + | Detail |
wal`histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))`
db`histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))`
| + | Summary |
wal`sum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))`
db`sum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))`
| + +## 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 |
volumes`sum(volumes_depth) by instance`
deployment`sum(deployment_depth) by instance`
replicaset`sum(replicaset_depth) by instance`
service`sum(service_depth) by instance`
serviceaccount`sum(serviceaccount_depth) by instance`
endpoint`sum(endpoint_depth) by instance`
daemonset`sum(daemonset_depth) by instance`
statefulset`sum(statefulset_depth) by instance`
replicationmanager`sum(replicationmanager_depth) by instance`
| + | Summary |
volumes`sum(volumes_depth)`
deployment`sum(deployment_depth)`
replicaset`sum(replicaset_depth)`
service`sum(service_depth)`
serviceaccount`sum(serviceaccount_depth)`
endpoint`sum(endpoint_depth)`
daemonset`sum(daemonset_depth)`
statefulset`sum(statefulset_depth)`
replicationmanager`sum(replicationmanager_depth)`
| + +- **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 |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)`
accpeted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)`
| + | Summary |
reading`sum(nginx_ingress_controller_nginx_process_connections{state="reading"})`
waiting`sum(nginx_ingress_controller_nginx_process_connections{state="waiting"})`
writing`sum(nginx_ingress_controller_nginx_process_connections{state="writing"})`
accpeted`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))`
active`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))`
handled`sum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))`
| + +- **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 + +- **CPU Utilization** + + | Catalog | Expression | + | --- | --- | + | Detail |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| + | Summary |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +- **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!=""})` | + +- **Network Packets** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| + | Summary |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +- **Network I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| + | Summary |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +- **Disk I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)`
| + | Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))`
| + +### Pod Metrics + +- **CPU Utilization** + + | Catalog | Expression | + | --- | --- | + | Detail |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)`
| + | Summary |
cfs throttled seconds`sum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
usage seconds`sum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
system seconds`sum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
user seconds`sum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))`
| + +- **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!=""})` | + +- **Network Packets** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + | Summary |
receive-packets`sum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-dropped`sum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
receive-errors`sum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-packets`sum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-dropped`sum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit-errors`sum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +- **Network I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + | Summary |
receive`sum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
transmit`sum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +- **Disk I/O** + + | Catalog | Expression | + | --- | --- | + | Detail |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)`
| + | Summary |
read`sum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
write`sum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))`
| + +### Container Metrics + +- **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]))` | + +- **Memory Utilization** + + `sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})` + +- **Disk IO** + + | 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]))` | + + diff --git a/content/rancher/v2.x/en/tools/pipelines/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/_index.md similarity index 98% rename from content/rancher/v2.x/en/tools/pipelines/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/_index.md index 55b0e7bf0f6..049c628599c 100644 --- a/content/rancher/v2.x/en/tools/pipelines/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/_index.md @@ -1,9 +1,10 @@ --- title: Pipelines -weight: 5005 +weight: 2529 aliases: - /rancher/v2.x/en/concepts/ci-cd-pipelines/ - /rancher/v2.x/en/tasks/pipelines/ + - /rancher/v2.x/en/tools/pipelines/ --- >**Notes:** > diff --git a/content/rancher/v2.x/en/tools/pipelines/concepts/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/concepts/_index.md similarity index 96% rename from content/rancher/v2.x/en/tools/pipelines/concepts/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/concepts/_index.md index 4c2d65e3c23..95419260441 100644 --- a/content/rancher/v2.x/en/tools/pipelines/concepts/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/concepts/_index.md @@ -1,6 +1,8 @@ --- title: Pipeline Terminology weight: 1000 +aliases: + - /rancher/v2.x/en/tools/pipelines/concepts/ --- When setting up a pipeline, it's helpful to know a few related terms. @@ -15,7 +17,7 @@ When setting up a pipeline, it's helpful to know a few related terms. - **Steps:** - A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than `0`. If a step exits with this failure code, the entire pipeline fails and terminates. + A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than `0`. If a step exits with this failure code, the entire pipeline fails and terminates. - **Workspace:** diff --git a/content/rancher/v2.x/en/tools/pipelines/configurations/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/configurations/_index.md similarity index 98% rename from content/rancher/v2.x/en/tools/pipelines/configurations/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/configurations/_index.md index ea9b6fc8cd2..23ba70da58d 100644 --- a/content/rancher/v2.x/en/tools/pipelines/configurations/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/configurations/_index.md @@ -1,6 +1,8 @@ --- title: Configuring Pipelines weight: 3725 +aliases: + - /rancher/v2.x/en/tools/pipelines/configurations/ --- Configuring a pipeline automates the process of triggering and publishing builds. This section describes how to set up a pipeline in a production environment. @@ -546,11 +548,11 @@ You can also set trigger rules to have fine-grained control of pipeline executio - **Do Not Run this when:** - This type of rule skips the pipeline, stage, or step when a trigger explicitly occurs. If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a pipeline is skipped, no execution will be triggered. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run. Wildcard character (`*`) expansion is supported in conditions. + {{% tabs %}} {{% tab "Pipeline Trigger" %}} @@ -566,23 +568,6 @@ If all conditions evaluate to true, then the pipeline/stage/step is executed. Ot 1. **Optional:** Add more branches that trigger a build. -{{% /accordion %}} - -{{% accordion id="pipeline-settings" label="While Editing Pipeline Settings" %}} - -After you've configured a pipeline, you can go back and choose the events that trigger a pipeline execution. - ->**Note:** This option is not available for example repositories. - -1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. - -1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Setting**. - -1. Select (or clear) the events that you want to trigger a pipeline execution. - -1. Click **Save**. -{{% /accordion %}} - {{% /tab %}} {{% tab "Stage Trigger" %}} 1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab. diff --git a/content/rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/docs-for-v2.0.x/_index.md similarity index 98% rename from content/rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/docs-for-v2.0.x/_index.md index adf02862bde..0afe3b45e5f 100644 --- a/content/rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/docs-for-v2.0.x/_index.md @@ -1,6 +1,8 @@ --- title: v2.0.x Pipeline Documentation weight: 9000 +aliases: + - /rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x --- >**Note:** This section describes the pipeline feature as implemented in Rancher v2.0.x. If you are using Rancher v2.1 or later, where pipelines have been significantly improved, please refer to the new documentation for [v2.1 or later]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines). diff --git a/content/rancher/v2.x/en/tools/pipelines/quick-start-guide/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/quick-start-guide/_index.md similarity index 93% rename from content/rancher/v2.x/en/tools/pipelines/quick-start-guide/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/quick-start-guide/_index.md index c23356ac307..7a510cae9e4 100644 --- a/content/rancher/v2.x/en/tools/pipelines/quick-start-guide/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/quick-start-guide/_index.md @@ -1,6 +1,8 @@ --- title: Pipelines Quick Start Guide weight: 500 +aliases: + - /rancher/v2.x/en/tools/pipelines/quick-start-guide/ --- Rancher ships with several example repositories that you can use to familiarize yourself with pipelines. We recommend configuring and testing the example repository that most resembles your environment before using pipelines with your own repositories in a production environment. Use this example repository as a sandbox for repo configuration, build demonstration, etc. Rancher includes example repositories for: @@ -20,12 +22,12 @@ By default, the example pipeline repositories are disabled. Enable one (or more) 1. Click **Configure Repositories**. **Step Result:** A list of example repositories displays. - + >**Note:** Example repositories only display if you haven't fetched your own repos. 1. Click **Enable** for one of the example repos (e.g., `https://github.com/rancher/pipeline-example-go.git`). Then click **Done**. -**Results:** +**Results:** - A pipeline is configured for the example repository, and it's added to the **Pipeline** tab. - The following workloads are deployed to a new namespace: @@ -38,7 +40,7 @@ By default, the example pipeline repositories are disabled. Enable one (or more) After configuring an example repository, run the pipeline to see how it works. -1. From the **Pipelines** tab, select **Ellipsis (...) > Run**. +1. From the **Pipelines** tab, select **Ellipsis (...) > Run**. >**Note:** When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components. To understand what the example pipeline is doing, select `Ellipsis (...) > Edit Config` for your repo. Alternatively, view the `.rancher-pipeline.yml` file in the example repositories. diff --git a/content/rancher/v2.x/en/tools/pipelines/reference/_index.md b/content/rancher/v2.x/en/project-admin/tools/pipelines/reference/_index.md similarity index 97% rename from content/rancher/v2.x/en/tools/pipelines/reference/_index.md rename to content/rancher/v2.x/en/project-admin/tools/pipelines/reference/_index.md index 54fb70dd065..280d3954fec 100644 --- a/content/rancher/v2.x/en/tools/pipelines/reference/_index.md +++ b/content/rancher/v2.x/en/project-admin/tools/pipelines/reference/_index.md @@ -1,6 +1,8 @@ --- title: Pipeline Variable Reference weight: 8000 +aliases: + - /rancher/v2.x/en/tools/pipelines/reference/ --- For your convenience, the following variables are available for your pipeline configuration scripts. During pipeline executions, these variables are replaced by metadata. You can reference them in the form of `${VAR_NAME}`. diff --git a/content/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/_index.md b/content/rancher/v2.x/en/removing-rancher/_index.md similarity index 78% rename from content/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/_index.md rename to content/rancher/v2.x/en/removing-rancher/_index.md index b9311ebcbf2..9833e07ceb5 100644 --- a/content/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/_index.md +++ b/content/rancher/v2.x/en/removing-rancher/_index.md @@ -1,8 +1,20 @@ --- -title: Removing Rancher from Your Rancher Server Nodes -weight: 2000 +title: Removing Rancher Server +weight: 7501 +aliases: + - /rancher/v2.x/en/installation/removing-rancher/cleaning-cluster-nodes/ + - /rancher/v2.x/en/installation/removing-rancher/ + - /rancher/v2.x/en/admin-settings/removing-rancher/ + - /rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/ --- +When you deploy Rancher and use it to provision clusters, Rancher installs its components on the nodes you use. There are two contexts in which you'd remove Rancher from a Kubernetes cluster node. + +- **Removing Rancher from Your Rancher Server Nodes**: In this context, you are removing Rancher from the Kubernetes cluster that you configured for your [Rancher installation]({{< baseurl >}}/rancher/v2.x/en/installation/ha/). This is outlined below. +- **[Removing Rancher Components from Rancher Launched Kubernetes Clusters]({{< baseurl >}}/rancher/v2.x/en/admin-settings/removing-rancher/user-cluster-nodes/)**: In this context, you are removing Rancher components from Kubernetes clusters that you [launched using Rancher]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). + +## Removing Rancher from a Rancher Installation + When you want to remove Rancher from your [installation cluster]({{< baseurl >}}/rancher/v2.x/en/installation/ha/) as part of a Rancher reinstall (or uninstall), follow the instructions below to download and run _system-tools_, a utility that removes all Rancher components from Rancher Server nodes provisioned by RKE. ### Download and Configuration diff --git a/content/rancher/v2.x/en/security/_index.md b/content/rancher/v2.x/en/security/_index.md index ff9b88d6447..1524ce23a26 100644 --- a/content/rancher/v2.x/en/security/_index.md +++ b/content/rancher/v2.x/en/security/_index.md @@ -1,5 +1,5 @@ --- -title: Rancher Security +title: Security weight: 7505 --- diff --git a/content/rancher/v2.x/en/tools/notifiers-and-alerts/_index.md b/content/rancher/v2.x/en/tools/notifiers-and-alerts/_index.md deleted file mode 100644 index 4b2f5e41ab9..00000000000 --- a/content/rancher/v2.x/en/tools/notifiers-and-alerts/_index.md +++ /dev/null @@ -1,455 +0,0 @@ ---- -title: Alerts and Notifiers -weight: 5010 ---- - -Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Notifiers are objects that you configure to leverage popular IT services, which send you notification of Rancher events. Alerts are rule sets that trigger when those notifications are sent. - -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]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) and [project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) of events they need to address. - -## Notifiers - -Before you can receive [alerts](#alerts), you must configure one or more notifier in Rancher. - -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. - -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. - -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**: Send alert notifications to your Enterprise WeChat contacts. -
-
- -### 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. -{{% accordion id="slack" label="Slack" %}} -1. Enter a **Name** for the notifier. -1. From Slack, create a webhook. For instructions, see the [Slack Documentation](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack). -1. From Rancher, enter your Slack webhook **URL**. -1. Enter the name of the channel that you want to send alert notifications in the following format: `#`. - - Both public and private channels are supported. -1. Click **Test**. If the test is successful, the Slack channel you're configuring for the notifier outputs `Slack setting validated`. -{{% /accordion %}} -{{% accordion id="email" label="Email" %}} -1. Enter a **Name** for the notifier. -1. In the **Sender** field, enter an email address available on your mail server that you want to send the notification. -1. In the **Host** field, enter the IP address or hostname for your SMTP server. Example: `smtp.email.com` -1. In the **Port** field, enter the port used for email. Typically, TLS uses `587` and SSL uses `465`. If you're using TLS, make sure **Use TLS** is selected. -1. Enter a **Username** and **Password** that authenticate with the SMTP server. -1. In the **Default Recipient** field, enter the email address that you want to receive the notification. -1. Click **Test**. If the test is successful, Rancher prints `settings validated` and you receive a test notification email. -{{% /accordion %}} -{{% accordion id="pagerduty" label="PagerDuty" %}} -1. Enter a **Name** for the notifier. -1. From PagerDuty, create a webhook. For instructions, see the [PagerDuty Documentation](https://support.pagerduty.com/docs/webhooks). -1. From PagerDuty, copy the webhook's **Integration Key**. -1. From Rancher, enter the key in the **Service Key** field. -1. Click **Test**. If the test is successful, your PagerDuty endpoint outputs `PageDuty setting validated`. -{{% /accordion %}} -{{% accordion id="webhook" label="WebHook" %}} -1. Enter a **Name** for the notifier. -1. Using the app of your choice, create a webhook URL. -1. Enter your webhook **URL**. -1. Click **Test**. If the test is successful, the URL you're configuring as a notifier outputs `Webhook setting validated`. -{{% /accordion %}} -{{% accordion id="WeChat" label="WeChat" %}} - -_Available as of v2.2.0_ - -1. Enter a **Name** for the notifier. -1. In the **Corporation ID** field, enter the "EnterpriseID" of your corporation, you could get it from [Profile page](https://work.weixin.qq.com/wework_admin/frame#profile). -1. From Enterprise WeChat, create an application in the [Application page](https://work.weixin.qq.com/wework_admin/frame#apps), and then enter the "AgentId" and "Secret" of this application to the **Application Agent ID** and **Application Secret** fields. -1. Select the **Recipient Type** and then enter a corresponding id to **Default Recipient** field, for example, 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). -{{% /accordion %}} - -1. Click **Add** to complete adding the notifier. - -**Result:** Your notifier is added to Rancher. - -#### What's Next? - -After creating a notifier, set up alerts to receive notifications of Rancher system events. - -- [Cluster owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) can set up alerts at the [cluster level](#cluster-alerts). -- [Project owners]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) can set up alerts at the [project level](#project-alerts). -
-
- -### Managing Notifiers - -After you set up notifiers, you can manage them by selecting **Tools > Notifiers** from the **Global** view. 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. - -## Alerts - -To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. To help you stay informed of these events, you can configure alerts. - -Alerts are sets of rules, chosen by you, to monitor for specific events. The scope for alerts can be set at either the cluster or project level. - -### Cluster Alerts vs. Project Alerts - -At the [cluster level](#adding-cluster-alerts), 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 - -At the [project level](#adding-project-alerts), Rancher monitors specific deployments and sends alerts for: - -* Deployment availability -* Workloads status -* Pod status -* The Prometheus expression cross the thresholds -
-
- -#### Adding Cluster Alerts - -As a cluster owner, you can configure Rancher to send you alerts for cluster events. - ->**Prerequisite:** Before you can receive cluster alerts, you must [add a notifier](#adding-notifiers). - -1. From the **Global** view, open the cluster that you want to configure alerts for. - -1. From the main menu, 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, complete one of the instruction subsets below. -{{% accordion id="system-service" label="System Service Alerts" %}} -This alert type monitor for events that affect one of the Kubernetes master components, regardless of the node it occurs on. - -1. Select the **System Services** option, and then select an option from the drop-down. - - - [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) - -1. 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. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="resource-event" label="Resource Event Alerts" %}} -This alert type monitors for specific events that are thrown from a resource type. - -1. 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. - -1. 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/) - -1. 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**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="node" label="Node Alerts" %}} -This alert type monitors for events that occur on a specific node. - -1. Select the **Node** option, and then make a selection from the **Choose a Node** drop-down. - -1. 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. - -1. 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**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="node-selector" label="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/). - -1. 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. - -1. 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. - -1. 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**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="cluster-expression" label="Metric Expression Alerts" %}} -This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring. - -1. Input or select an **Expression**, the drop down shows the original metrics from Prometheus, including: - - - [**Node**](https://github.com/prometheus/node_exporter) - - [**Container**](https://github.com/google/cadvisor) - - [**ETCD**](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/monitoring.md) - - [**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]({{< baseurl >}}/rancher/v2.x/en/tools/logging)) - - [**Cluster Level Grafana**](http://docs.grafana.org/administration/metrics/) - - **Cluster Level Prometheus** - -1. 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. - -1. Input a **Threshold**, for trigger alert when the value of expression cross the threshold. - -1. Choose a **Comparison**. - -1. Select a duration, for trigger alert when expression value crosses the threshold longer than the configured duration. - -1. 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**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} - -1. Continue adding more **Alert Rule** to the group. - -1. Finally, choose the notifiers that send you alerts. - - - You can set up multiple notifiers. - - You can change notifier recipients on the fly. - -**Result:** Your alert is configured. A notification is sent when the alert is triggered. - -#### 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 Project Alerts - ->**Prerequisite:** Before you can receive project alerts, you must [add a notifier](#adding-notifiers). - -1. From the **Global** view, open the project that you want to configure alerts for. - -1. From the main menu, select **Tools > Alerts**. In versions prior to v2.2.0, you can choose **Resources > Alerts**. - -1. 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, complete one of the instruction subsets below. -{{% accordion id="pod" label="Pod Alerts" %}} -This alert type monitors for the status of a specific pod. - -1. Select the **Pod** option, and then select a pod from the drop-down. -1. Select a pod status that triggers an alert: - - - **Not Running** - - **Not Scheduled** - - **Restarted `` times with the last `` Minutes** - -1. Select the urgency level of the alert. The options are: - - - **Critical**: Most urgent - - **Warning**: Normal urgency - - **Info**: Least urgent - - Select the urgency level of the alert based on pod state. For example, select **Info** for Job pod which stop running after job finished. However, if an important pod isn't scheduled, it may affect operations, so choose **Critical**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="workload" label="Workload Alerts" %}} -This alert type monitors for the availability of a workload. - -1. Choose the **Workload** option. Then choose a workload from the drop-down. - -1. Choose an availability percentage using the slider. The alert is triggered when the workload's availability on your cluster nodes drops below the set percentage. - -1. Select the urgency level of the alert. - - - **Critical**: Most urgent - - **Warning**: Normal urgency - - **Info**: Least urgent - - Select the urgency level of the alert based on the percentage you choose and the importance of the workload. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="workload-selector" label="Workload Selector Alerts" %}} -This alert type monitors for the availability of all workloads marked with tags that you've specified. - -1. Select the **Workload Selector** option, and then click **Add Selector** to enter the key value pair for a label. If one of the workloads drops below your specifications, an alert is triggered. This label should be applied to one or more of your workloads. - -1. Select the urgency level of the alert. - - - **Critical**: Most urgent - - **Warning**: Normal urgency - - **Info**: Least urgent - - Select the urgency level of the alert based on the percentage you choose and the importance of the workload. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} -{{% accordion id="project-expression" label="Metric Expression Alerts" %}} -This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring. - -1. Input or select an **Expression**, the drop down shows the original metrics from Prometheus, including: - - - [**Container**](https://github.com/google/cadvisor) - - [**Kubernetes Resources**](https://github.com/kubernetes/kube-state-metrics) - - [**Customize**]({{< baseurl >}}/rancher/v2.x/en/tools/monitoring/#custom-metrics) - - [**Project Level Grafana**](http://docs.grafana.org/administration/metrics/) - - **Project Level Prometheus** - -1. 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. - -1. Input a **Threshold**, for trigger alert when the value of expression cross the threshold. - -1. Choose a **Comparison**. - -1. Select a **Duration**, for trigger alert when expression value crosses the threshold longer than the configured duration. - -1. Select the urgency level of the alert. - - - **Critical**: Most urgent - - **Warning**: Normal urgency - - **Info**: Least urgent -
-
- Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a expression for container memory close to the limit raises above 60% deems an urgency of **Info**, but raised about 95% deems an urgency of **Critical**. - -1. Configure advanced options. By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule. - - - **Group Wait Time**: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds. - - **Group Interval Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds. - - **Repeat Wait Time**: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour. - -{{% /accordion %}} - -1. Continue adding more **Alert Rule** to the group. - -1. Finally, choose the notifiers that send you alerts. - - - You can set up multiple notifiers. - - You can change notifier recipients on the fly. - -**Result:** Your alert is configured. A notification is sent when the alert is triggered. - -#### Managing Project Alerts - -To manage project alerts, browse to the project that alerts you want to manage. Then select **Tools > Alerts**. In versions prior to v2.2.0, you can choose **Resources > Alerts**. You can: - -- Deactivate/Reactive alerts -- Edit alert settings -- Delete unnecessary alerts -- Mute firing alerts -- Unmute muted alerts diff --git a/content/rancher/v2.x/en/v1.6-migration/_index.md b/content/rancher/v2.x/en/v1.6-migration/_index.md index 3a8a0c463a2..8d065e00458 100644 --- a/content/rancher/v2.x/en/v1.6-migration/_index.md +++ b/content/rancher/v2.x/en/v1.6-migration/_index.md @@ -1,5 +1,5 @@ --- -title: Migrating from Rancher v1.6 to v2.x +title: Migrating from v1.6 to v2.x weight: 10000 --- @@ -31,11 +31,11 @@ This video demonstrates a complete walk through of migration from Rancher v1.6 t ## Migration Example Files -Throughout this migration guide, we will reference several example services from Rancher v1.6 that we're migrating to v2.x. These services are: +Throughout this migration guide, we will reference several example services from Rancher v1.6 that we're migrating to v2.x. These services are: - A service named `web`, which runs [Let's Chat](http://sdelements.github.io/lets-chat/), a self-hosted chat for small teams. - A service named `database`, which runs [Mongo DB](https://www.mongodb.com/), an open source document database. -- A service named `webLB`, which runs [HAProxy](http://www.haproxy.org/), an open source load balancer used in Rancher v1.6. +- A service named `webLB`, which runs [HAProxy](http://www.haproxy.org/), an open source load balancer used in Rancher v1.6. During migration, we'll export these services from Rancher v1.6. The export generates a unique directory for each Rancher v1.6 environment and stack, and two files are output into each stack's directory: @@ -48,4 +48,4 @@ During migration, we'll export these services from Rancher v1.6. The export gen A file for Rancher-specific functionality such as health checks and load balancers. These files cannot be read by Rancher v2.x, so don't worry about their contents—we're discarding them and recreating them using the v2.x UI. -### [Next: Get Started]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/get-started) \ No newline at end of file +### [Next: Get Started]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/get-started)