diff --git a/content/k3s/latest/en/installation/private-registry/_index.md b/content/k3s/latest/en/installation/private-registry/_index.md index 1abbc473cd1..523ae6c8586 100644 --- a/content/k3s/latest/en/installation/private-registry/_index.md +++ b/content/k3s/latest/en/installation/private-registry/_index.md @@ -163,4 +163,4 @@ Example: `docker tag coredns-coredns:1.6.3 mycustomreg:5000/coredns-coredns` Last, push the images to the private registry. -Example: `docker push mycustomreg:5000/coredns-coredns` +Example: `docker push mycustomreg.com:5000/coredns-coredns` diff --git a/content/rancher/v2.0-v2.4/en/installation/requirements/_index.md b/content/rancher/v2.0-v2.4/en/installation/requirements/_index.md index ef77bd8dd89..fbf442d663e 100644 --- a/content/rancher/v2.0-v2.4/en/installation/requirements/_index.md +++ b/content/rancher/v2.0-v2.4/en/installation/requirements/_index.md @@ -78,7 +78,8 @@ Performance increased in Rancher v2.4.0. For the requirements of Rancher before | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. + {{% /tab %}} {{% tab "K3s" %}} @@ -93,7 +94,7 @@ These requirements apply to each host in a [K3s Kubernetes cluster where the Ran | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. {{% /tab %}} diff --git a/content/rancher/v2.5/en/admin-settings/authentication/ad/_index.md b/content/rancher/v2.5/en/admin-settings/authentication/ad/_index.md index 0cce01d449d..2c9c82a4374 100644 --- a/content/rancher/v2.5/en/admin-settings/authentication/ad/_index.md +++ b/content/rancher/v2.5/en/admin-settings/authentication/ad/_index.md @@ -101,7 +101,7 @@ The table below details the parameters for the group schema configuration. | Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. | | Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. | | Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. | -| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members. We advise avoiding nested groups when possible). | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible). | --- @@ -153,7 +153,7 @@ This command performs an LDAP search with the search base set to the domain root Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`. -Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, ie. `OU=Groups,DC=acme,DC=com`. +Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, i.e., `OU=Groups,DC=acme,DC=com`. ### Identify User Schema @@ -166,7 +166,7 @@ The output of the above `ldapsearch` query also allows to determine the correct > **Note:** > -> If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. +> If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name. diff --git a/content/rancher/v2.5/en/installation/requirements/_index.md b/content/rancher/v2.5/en/installation/requirements/_index.md index 3c8c1dd3f20..41eda67564e 100644 --- a/content/rancher/v2.5/en/installation/requirements/_index.md +++ b/content/rancher/v2.5/en/installation/requirements/_index.md @@ -126,7 +126,7 @@ These requirements apply to RKE Kubernetes clusters, as well as to hosted Kubern | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. ### K3s Kubernetes @@ -140,7 +140,7 @@ These CPU and memory requirements apply to each host in a [K3s Kubernetes cluste | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. ### RancherD diff --git a/content/rancher/v2.6/en/admin-settings/authentication/ad/_index.md b/content/rancher/v2.6/en/admin-settings/authentication/ad/_index.md index a919075bdaa..251039f2c97 100644 --- a/content/rancher/v2.6/en/admin-settings/authentication/ad/_index.md +++ b/content/rancher/v2.6/en/admin-settings/authentication/ad/_index.md @@ -101,7 +101,7 @@ The table below details the parameters for the group schema configuration. | Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. | | Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. | | Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. | -| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members. We advise avoiding nested groups when possible). | +| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible to avoid potential performance issues when there is a large amount of nested memberships). | --- @@ -153,7 +153,7 @@ This command performs an LDAP search with the search base set to the domain root Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`. -Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, ie. `OU=Groups,DC=acme,DC=com`. +Similarly, based on the DN of the group referenced in the **memberOf** attribute [4], the correct value for the **Group Search Base** would be the parent node of that value, i.e., `OU=Groups,DC=acme,DC=com`. ### Identify User Schema @@ -166,7 +166,7 @@ The output of the above `ldapsearch` query also allows to determine the correct > **Note:** > -> If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. +> If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the `Login Attribute` to **userPrincipalName** instead. We'll also set the `Search Attribute` parameter to **sAMAccountName|name**. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name. diff --git a/content/rancher/v2.6/en/backups/restoring-rancher/_index.md b/content/rancher/v2.6/en/backups/restoring-rancher/_index.md index 468b179d348..2ec7691aa79 100644 --- a/content/rancher/v2.6/en/backups/restoring-rancher/_index.md +++ b/content/rancher/v2.6/en/backups/restoring-rancher/_index.md @@ -3,16 +3,7 @@ title: Restoring Rancher weight: 2 --- -A restore is performed by creating a Restore custom resource. - ---- -**Caution:** Before performing a restore or rollback, note the following: - -- In Rancher v2.6.4, the cluster-api module has been upgraded from v0.4.4 to v1.0.2 in which the apiVersion of CAPI CRDs are upgraded from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. This has the effect of causing rollbacks from Rancher v2.6.4 to any previous version of Rancher v2.6.x to fail because the previous version the CRDs needed to roll back are no longer available in v1beta1. - -- To avoid this, the Rancher resource cleanup scripts should be run **before** the restore or rollback is attempted. Specifically, two scripts have been created to assist you: one to clean up the cluster (`cleanup.sh`), and one to check for any Rancher-related resources in the cluster (`verify.sh`). Details on the cleanup script can be found in the [rancherlabs/support-tools repo](https://github.com/rancherlabs/support-tools/tree/master/cleanup-rancher-k8s-resources). - ---- +This page outlines how to perform a restore with Rancher. > **Important** > @@ -20,8 +11,25 @@ A restore is performed by creating a Restore custom resource. > * While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. > * If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.]({{}}/rancher/v2.6/en/installation/install-rancher-on-k8s/rollbacks/) +### Additional Steps for Rollbacks with Rancher v2.6.4+ + +In Rancher v2.6.4, the cluster-api module has been upgraded from v0.4.4 to v1.0.2 in which the apiVersion of CAPI CRDs are upgraded from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. This has the effect of causing rollbacks from Rancher v2.6.4 to any previous version of Rancher v2.6.x to fail because the previous version the CRDs needed to roll back are no longer available in v1beta1. + +To avoid this, the Rancher resource cleanup scripts should be run **before** the restore or rollback is attempted. Specifically, two scripts have been created to assist you: one to clean up the cluster (`cleanup.sh`), and one to check for any Rancher-related resources in the cluster (`verify.sh`). Details on the cleanup script can be found in the [rancherlabs/support-tools repo](https://github.com/rancherlabs/support-tools/tree/master/rancher-cleanup). + +> **Caution** Rancher will be down as the `cleanup` script runs as it deletes the resources created by rancher. + +The additional preparations: + +1. Follow these [instructions](https://github.com/rancherlabs/support-tools/blob/master/rancher-cleanup/README.md) to run the scripts. +1. Follow these [instructions](https://rancher.com/docs/rancher/v2.6/en/backups/migrating-rancher/) to install the rancher-backup Helm chart on the existing cluster and restore the previous state. + 1. Omit Step 3. + 1. When Step 4 is reached, install the required Rancher v2.6.x version on the local cluster you intend to roll back to. + ### Create the Restore Custom Resource +A restore is performed by creating a Restore custom resource. + 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the `local` cluster and click **Explore**. The `local` cluster runs the Rancher server. 1. In the left navigation bar, click **Rancher Backups > Restores**. @@ -74,6 +82,6 @@ In some cases, after restoring the backup, Rancher logs will show errors similar ``` 2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing ``` -This happens because one of the resources that was just restored has finalizers but the related resources have been deleted so the handler cannot find it. +This happens because one of the resources that was just restored has finalizers, but the related resources have been deleted so the handler cannot find it. To eliminate the errors, we need to find and delete the resource that causes the error. See more information [here](https://github.com/rancher/rancher/issues/35050#issuecomment-937968556) diff --git a/content/rancher/v2.6/en/cli/_index.md b/content/rancher/v2.6/en/cli/_index.md index 89928a7dc9b..8998916acd2 100644 --- a/content/rancher/v2.6/en/cli/_index.md +++ b/content/rancher/v2.6/en/cli/_index.md @@ -1,5 +1,5 @@ --- -title: Using the Rancher Command Line Interface +title: Using the Rancher Command Line Interface description: The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI metaTitle: "Using the Rancher Command Line Interface " metaDescription: "The Rancher CLI is a unified tool that you can use to interact with Rancher. With it, you can operate Rancher using a command line interface rather than the GUI" @@ -12,6 +12,12 @@ The Rancher CLI (Command Line Interface) is a unified tool that you can use to i The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary. +The binary can be downloaded directly from the UI. + +1. In the upper left corner, click **☰**. +1. At the bottom, click **v2.6.x**, where **v2.6.x** is a hyperlinked text indicating the installed Rancher version. +1. Under the **CLI Downloads section**, there are links to download the binaries for Windows, Mac, and Linux. You can also check the [releases page for our CLI](https://github.com/rancher/cli/releases) for direct downloads of the binary. + ### Requirements After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires: @@ -36,11 +42,11 @@ Before you can perform any commands, you must select a Rancher project to perfor **Example: `./rancher context switch` Output** ``` User:rancher-cli-directory user$ ./rancher context switch -NUMBER CLUSTER NAME PROJECT ID PROJECT NAME -1 cluster-2 c-7q96s:p-h4tmb project-2 -2 cluster-2 c-7q96s:project-j6z6d Default -3 cluster-1 c-lchzv:p-xbpdt project-1 -4 cluster-1 c-lchzv:project-s2mch Default +NUMBER CLUSTER NAME PROJECT ID PROJECT NAME +1 cluster-2 c-7q96s:p-h4tmb project-2 +2 cluster-2 c-7q96s:project-j6z6d Default +3 cluster-1 c-lchzv:p-xbpdt project-1 +4 cluster-1 c-lchzv:project-s2mch Default Select a Project: ``` @@ -78,3 +84,7 @@ The following commands are available for use in Rancher CLI. Once logged into Rancher Server using the CLI, enter `./rancher --help` for a list of commands. All commands accept the `--help` flag, which documents each command's usage. + +### Limitations + +The Rancher CLI **cannot** be used to install [dashboard apps or Rancher feature charts](../helm-charts/). diff --git a/content/rancher/v2.6/en/cluster-admin/certificate-rotation/_index.md b/content/rancher/v2.6/en/cluster-admin/certificate-rotation/_index.md index 664af10b1fc..c38a4dd0d5b 100644 --- a/content/rancher/v2.6/en/cluster-admin/certificate-rotation/_index.md +++ b/content/rancher/v2.6/en/cluster-admin/certificate-rotation/_index.md @@ -9,6 +9,9 @@ By default, Kubernetes clusters require certificates and Rancher launched Kubern Certificates can be rotated for the following services: +{{% tabs %}} +{{% tab "RKE" %}} + - etcd - kubelet (node certificate) - kubelet (serving certificate, if [enabled]({{}}/rke/latest/en/config-options/services/#kubelet-options)) @@ -17,6 +20,24 @@ Certificates can be rotated for the following services: - kube-scheduler - kube-controller-manager +{{% /tab %}} +{{% tab "RKE2" %}} + +- admin +- api-server +- controller-manager +- scheduler +- rke2-controller +- rke2-server +- cloud-controller +- etcd +- auth-proxy +- kubelet +- kube-proxy + +{{% /tab %}} +{{% /tabs %}} + > **Note:** For users who didn't rotate their webhook certificates, and they have expired after one year, please see this [page]({{}}/rancher/v2.6/en/troubleshooting/expired-webhook-certificates/) for help. @@ -24,17 +45,28 @@ Certificates can be rotated for the following services: Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI. -1. In the **Global** view, navigate to the cluster that you want to rotate certificates. - -2. Select **⋮ > Rotate Certificates**. - -3. Select which certificates that you want to rotate. +1. In the upper left corner, click **☰ > Cluster Management**. +1. On the **Clusters** page, go to the cluster you want to rotate certificates for amd click **⋮ > Rotate Certificates**. +1. Select which certificates that you want to rotate. * Rotate all Service certificates (keep the same CA) * Rotate an individual service and choose one of the services from the drop-down menu -4. Click **Save**. +1. Click **Save**. **Results:** The selected certificates will be rotated and the related services will be restarted to start using the new certificate. -> **Note:** Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher launched Kubernetes clusters. +### Additional Notes + +{{% tabs %}} +{{% tab "RKE" %}} + +Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher launched Kubernetes clusters. + +{{% /tab %}} +{{% tab "RKE2" %}} + +In RKE2, both etcd and control plane nodes are treated as the same `server` concept. As such, when rotating certificates of services specific to either of these components will result in certificates being rotated on both. The certificates will only change for the specified service, but you will see nodes for both components go into an updating state. You may also see worker only nodes go into an updating state. This is to restart the workers after a certificate change to ensure they get the latest client certs. + +{{% /tab %}} +{{% /tabs %}} diff --git a/content/rancher/v2.6/en/cluster-admin/editing-clusters/_index.md b/content/rancher/v2.6/en/cluster-admin/editing-clusters/_index.md index c9e257784be..cab7cdd0d06 100644 --- a/content/rancher/v2.6/en/cluster-admin/editing-clusters/_index.md +++ b/content/rancher/v2.6/en/cluster-admin/editing-clusters/_index.md @@ -12,8 +12,8 @@ For information on editing cluster membership, go to [this page.]({{}}/ The cluster configuration options depend on the type of Kubernetes cluster: - [RKE Cluster Configuration](./rke-config-reference) -- [RKE2 Cluster Configuration](./rke2-config-reference) (Tech Preview) -- [K3s Cluster Configuration](./k3s-config-reference) (Tech Preview) +- [RKE2 Cluster Configuration](./rke2-config-reference) +- [K3s Cluster Configuration](./k3s-config-reference) - [EKS Cluster Configuration](./eks-config-reference) - [GKE Cluster Configuration](./gke-config-reference) - [AKS Cluster Configuration](./aks-config-reference) diff --git a/content/rancher/v2.6/en/cluster-admin/editing-clusters/k3s-config-reference/_index.md b/content/rancher/v2.6/en/cluster-admin/editing-clusters/k3s-config-reference/_index.md index 47ee18b44e2..00d784cfa0c 100644 --- a/content/rancher/v2.6/en/cluster-admin/editing-clusters/k3s-config-reference/_index.md +++ b/content/rancher/v2.6/en/cluster-admin/editing-clusters/k3s-config-reference/_index.md @@ -1,5 +1,5 @@ --- -title: K3s Cluster Configuration Reference (Tech Preview) +title: K3s Cluster Configuration Reference shortTitle: K3s Cluster Configuration weight: 6 --- diff --git a/content/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/_index.md b/content/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/_index.md index 54539ceb934..3e1ee54d5db 100644 --- a/content/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/_index.md +++ b/content/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/_index.md @@ -1,5 +1,5 @@ --- -title: RKE2 Cluster Configuration Reference (Tech Preview) +title: RKE2 Cluster Configuration Reference shortTitle: RKE2 Cluster Configuration weight: 5 --- @@ -41,6 +41,14 @@ Out of the box, Rancher is compatible with the following network providers: For more details on the different networking providers and how to configure them, please view our [RKE2 documentation](https://docs.rke2.io/install/network_options/). +##### Dual-stack Networking + +[Dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) networking is supported for all CNI providers. To configure RKE2 in dual-stack mode, set valid IPv4/IPv6 CIDRs for your [Cluster CIDR](#cluster-cidr) and/or [Service CIDR](#service-cidr). + +###### Additional Configuration {#dual-stack-additional-config} + +When using `cilium` or `multus,cilium` as your container network interface provider, ensure the **Enable IPv6 Support** option is also enabled. + #### Cloud Provider You can configure a [Kubernetes cloud provider]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/cloud-providers). If you want to use dynamically provisioned [volumes and storage]({{}}/rancher/v2.6/en/cluster-admin/volumes-and-storage/) in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the `aws` cloud provider. @@ -103,12 +111,24 @@ Option to choose whether to expose etcd metrics to the public or only within the #### Cluster CIDR -IPv4/IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16). +IPv4 and/or IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16). + +##### Dual-stack Networking + +To configure [dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) mode, enter a valid IPv4/IPv6 CIDR. For example `10.42.0.0/16,2001:cafe:42:0::/56`. + +[Additional configuration](#dual-stack-additional-config) is required when using `cilium` or `multus,cilium` as your [container network](#container-network) interface provider. #### Service CIDR IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16). +##### Dual-stack Networking + +To configure [dual-stack](https://docs.rke2.io/install/network_options/#dual-stack-configuration) mode, enter a valid IPv4/IPv6 CIDR. For example `10.42.0.0/16,2001:cafe:42:0::/56`. + +[Additional configuration](#dual-stack-additional-config) is required when using `cilium ` or `multus,cilium` as your [container network](#container-network) interface provider. + #### Cluster DNS IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10). @@ -166,5 +186,3 @@ Option to set kubelet options for different nodes. For available options, refer Instead of using the Rancher UI forms to choose Kubernetes options for the cluster, advanced users can create an RKE2 config file. Using a config file allows you to set any of the [options](https://docs.rke2.io/install/install_options/install_options) available in an RKE2 installation. To edit an RKE2 config file directly from the Rancher UI, click **Edit as YAML**. - - diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md index c918601b214..8e7deb9bf62 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md @@ -6,7 +6,7 @@ weight: 2220 In this section, you'll learn how to install an [RKE]({{}}/rke/latest/en/) Kubernetes cluster in Azure through Rancher. -First, you will set up your Azure cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in Azure. +First, you will set up your Azure cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in Azure. Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. @@ -25,29 +25,31 @@ For more information on configuring Azure node templates, refer to the [Azure no - [Creating an Azure Cluster](#creating-an-azure-cluster) # Preparation in Azure - + Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription. To do this, we will first create a new Azure **service principal (SP)** in Azure **Active Directory (AD)**, which, in Azure, is an application user who has permission to manage Azure resources. The following is a template `az cli` script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope: - + ``` az ad sp create-for-rbac \ --name="" \ --role="Contributor" \ --scopes="/subscriptions/" ``` - + The creation of this service principal returns three pieces of identification information, *The application ID, also called the client ID*, and *The client secret*. This information will be used when you create a node template for Azure. # Creating an Azure Cluster +{{% tabs %}} +{{% tab "RKE" %}} 1. [Create your cloud credentials](#1-create-your-cloud-credentials) 2. [Create a node template with your cloud credentials](#2-create-a-node-template-with-your-cloud-credentials) 3. [Create a cluster with node pools using the node template](#3-create-a-cluster-with-node-pools-using-the-node-template) - + ### 1. Create your cloud credentials 1. Click **☰ > Cluster Management**. @@ -57,7 +59,7 @@ The creation of this service principal returns three pieces of identification in 1. Enter your Azure credentials. 1. Click **Create**. -**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. ### 2. Create a node template with your cloud credentials @@ -82,17 +84,53 @@ Use Rancher to create a Kubernetes cluster in Azure. 1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. 1. Click **Create**. -**Result:** +{{% /tab %}} +{{% tab "RKE2" %}} + +### 1. Create your cloud credentials + +If you already have a set of cloud credentials to use, skip this section. + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **Azure**. +1. Enter your Azure credentials. +1. Click **Create**. + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. + +### 2. Create your cluster + +Use Rancher to create a Kubernetes cluster in Azure. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Toggle the switch to **RKE2/K3s**. +1. Click **Azure**. +1. Select a **Cloud Credential**, if more than one exists. Otherwise, it's preselected. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools#node-roles-in-rke2) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to the [Azure machine configuration reference]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/azure-machine-config/) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2 cluster configuration reference.]({{}}/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/) +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + +{{% /tab %}} +{{% /tabs %}} + +**Result:** Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. You can access your cluster after its state is updated to **Active**. -**Active** clusters are assigned two Projects: +**Active** clusters are assigned two Projects: - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + ### Optional Next Steps After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/azure-machine-config/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/azure-machine-config/_index.md new file mode 100644 index 00000000000..4c5304eb1e2 --- /dev/null +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/azure/azure-machine-config/_index.md @@ -0,0 +1,121 @@ +--- +title: Azure Machine Configuration +weight: 2 +--- + +For more information about Azure, refer to the official [Azure documentation.](https://docs.microsoft.com/en-us/azure/?product=featured) + +### Environment + +Microsoft provides multiple [clouds](https://docs.microsoft.com/en-us/cli/azure/cloud?view=azure-cli-latest) for compliance with regional laws, which are available for your use: + +- AzurePublicCloud +- AzureGermanCloud +- AzureChinaCloud +- AzureUSGovernmentCloud + +### Location + +Configure the cluster and node [location](https://docs.microsoft.com/en-us/azure/virtual-machines/regions). + +### Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group. + +Use an existing resource group or enter a resource group name and one will be created for you. + +For information on managing resource groups, see the [Azure documentation.](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) + +### Availability Set (unmanaged) + +Name or ID of an existing [availability set](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview) to add the VM to. + +### Image + +The name of the operating system image provided as an ARM resource identifier. Requires using managed disk. + +### VM Size + +Choose a size for each VM in the node pool. For details about each VM size, see [this page.](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) + +## Advanced Options + +### Fault Domain Count + +Fault domains define the group of virtual machines that share a common power source and network switch. If the availability set has already been created, the fault domain count will be ignored. + +For more information on fault domains, see [refer here](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work). + +### Update Domain Count + +Update domains indicate groups of virtual machines and underlying physical hardware that can be rebooted at the same time. If the availability set has already been created, the update domain count will be ignored. + +For more information on update domains, see [refer here](https://docs.microsoft.com/en-us/azure/virtual-machines/availability-set-overview#how-do-availability-sets-work). + +### Purchase Plan + +Some VM images in the Azure Marketplace require a plan. If applicable, select a purchase plan, formatted as `publisher:product:plan`, to use with your chosen image. + +### Subnet + +The name of the subnet when creating a new VNet or referencing an existing one. + +Default: `docker-machine` + +### Subnet Prefix + +The subnet IP address prefix to use when creating a new VNet in CIDR format. + +Default: `192.168.0.0/16` + +### Virtual Network + +The [virtual network](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview) to use or create if one does not exist. Formatted as `[resourcegroup:]name`. + +### Public IP Options + +#### No Public IP + +Do not allocate a public IP address. + +#### Static Public IP + +Allocate a static public IP address. + +### Use Private IP + +Use a static private IP address. + +### Private IP Address + +Configure a static private IP address to use. + +### Network Security Group + +The [network security group](https://docs.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview) to use. All nodes using this template will use the supplied network security group. If no network security group is provided, a new one will be created for each node. + +### DNS Label + +A unique DNS name label for the public IP address. + +### Storage Type + +The [storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview) type to use with your VMs. Options include Standard LRS, Standard ZRS, Standard GRS, Standard RAGRS, and Premium LRS. + +### Use Managed Disks + +[Azure managed disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability. + +### Managed Disk Size + +The size in GB for the disk for each node. + +### SSH Username + +The username used to create an SSH connection to your nodes. + +### Open Port + +Opens inbound traffic on specified ports. When using an existing Network Security Group, Open Ports are ignored. + +Default: `2379/tcp, 2380/tcp, 6443/tcp, 9796/tcp, 10250/tcp, 10251/tcp, 10252/tcp, 10256/tcp` and `8472/udp, 4789/udp` \ No newline at end of file diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md index 4c1903b9f63..7d3e103cd1e 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md @@ -5,10 +5,12 @@ weight: 2215 --- In this section, you'll learn how to use Rancher to install an [RKE](https://rancher.com/docs/rke/latest/en/) Kubernetes cluster in DigitalOcean. -First, you will set up your DigitalOcean cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in DigitalOcean. +First, you will set up your DigitalOcean cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in DigitalOcean. Then you will create a DigitalOcean cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool. +{{% tabs %}} +{{% tab "RKE" %}} 1. [Create your cloud credentials](#1-create-your-cloud-credentials) 2. [Create a node template with your cloud credentials](#2-create-a-node-template-with-your-cloud-credentials) @@ -23,7 +25,7 @@ Then you will create a DigitalOcean cluster in Rancher, and when configuring the 1. Enter your Digital Ocean credentials. 1. Click **Create**. -**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. ### 2. Create a node template with your cloud credentials @@ -46,13 +48,46 @@ Creating a [node template]({{}}/rancher/v2.6/en/cluster-provisioning/rk 1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. 1. Click **Create**. -**Result:** +{{% /tab %}} +{{% tab "RKE2" %}} + +### 1. Create your cloud credentials + +If you already have a set of cloud credentials to use, skip this section. + +1. Click **☰ > Cluster Management**. +1. Click **Cloud Credentials**. +1. Click **Create**. +1. Click **DigitalOcean**. +1. Enter your Digital Ocean credentials. +1. Click **Create**. + +### 2. Create your cluster + +Use Rancher to create a Kubernetes cluster in DigitalOcean. + +1. Click **☰ > Cluster Management**. +1. On the **Clusters** page, click **Create**. +1. Toggle the switch to **RKE2/K3s**. +1. Click **DigitalOcean**. +1. Select a **Cloud Credential**, if more than one exists. Otherwise, it's preselected. +1. Enter a **Cluster Name**. +1. Create a machine pool for each Kubernetes role. Refer to the [best practices]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools#node-roles-in-rke2) for recommendations on role assignments and counts. + 1. For each machine pool, define the machine configuration. Refer to the [DigitalOcean machine configuration reference]({{}}/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/do-machine-config/) for information on configuration options. +1. Use the **Cluster Configuration** to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. For help configuring the cluster, refer to the [RKE2 cluster configuration reference.]({{}}/rancher/v2.6/en/cluster-admin/editing-clusters/rke2-config-reference/) +1. Use **Member Roles** to configure user authorization for the cluster. Click **Add Member** to add users that can access the cluster. Use the **Role** drop-down to set permissions for each user. +1. Click **Create**. + +{{% /tab %}} +{{% /tabs %}} + +**Result:** Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. You can access your cluster after its state is updated to **Active**. -**Active** clusters are assigned two Projects: +**Active** clusters are assigned two Projects: - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces @@ -61,4 +96,4 @@ You can access your cluster after its state is updated to **Active**. After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster: - **Access your cluster with the kubectl CLI:** Follow [these steps]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/kubectl/#accessing-clusters-with-kubectl-on-your-workstation) to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI. -- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/kubectl/#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. \ No newline at end of file +- **Access your cluster with the kubectl CLI, using the authorized cluster endpoint:** Follow [these steps]({{}}/rancher/v2.6/en/cluster-admin/cluster-access/kubectl/#authenticating-directly-with-a-downstream-cluster) to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster. diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/do-machine-config/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/do-machine-config/_index.md new file mode 100644 index 00000000000..0ae2f8d831a --- /dev/null +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/do-machine-config/_index.md @@ -0,0 +1,34 @@ +--- +title: DigitalOcean Machine Configuration +weight: 2 +--- + +For more details about DigitalOcean, Droplets, refer to the [official documentation](https://docs.digitalocean.com/products/compute/). + +### Region + +Configure the [region](https://docs.digitalocean.com/products/app-platform/concepts/region/) where Droplets are created. + +### Size + +Configure the [size](https://docs.digitalocean.com/products/droplets/resources/choose-plan/) of Droplets. + +### OS Image + +Configure the operating system [image](https://docs.digitalocean.com/products/images/) Droplets are created from. + +### Monitoring + +Enable the DigitalOcean agent for additional [monitoring](https://docs.digitalocean.com/products/monitoring/). + +### IPv6 + +Enable IPv6 for Droplets. + +### Private Networking + +Enable private networking for Droplets. + +### Droplet Tags + +Apply a tag (label) to a Droplet. Tags may only contain letters, numbers, colons, dashes, and underscores. For example, `my_server`. diff --git a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md index ebd32e5397d..5db4add3d41 100644 --- a/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md +++ b/content/rancher/v2.6/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md @@ -30,11 +30,11 @@ This guide covers the following topics: # Changes in Rancher v2.6 -_Tech Preview_ - Rancher v2.6 introduces provisioning for [RKE2](https://docs.rke2.io/) clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. -The RKE2 provisioning tech preview also includes installing RKE2 on Windows clusters. Windows features for RKE2 include: +As of Rancher v2.6.5, provisioning for RKE2 is GA. + +The RKE2 provisioning feature also includes installing RKE2 on Windows clusters. Windows features for RKE2 include: - Windows Containers with RKE2 powered by containerd - Added provisioning of Windows RKE2 custom clusters directly from the Rancher UI diff --git a/content/rancher/v2.6/en/contributing/_index.md b/content/rancher/v2.6/en/contributing/_index.md index 3900cabb57f..cb8d8332c8e 100644 --- a/content/rancher/v2.6/en/contributing/_index.md +++ b/content/rancher/v2.6/en/contributing/_index.md @@ -24,7 +24,7 @@ Repository | URL | Description Rancher | https://github.com/rancher/rancher | This repository is the main source code for Rancher 2.x. Types | https://github.com/rancher/types | This repository is the repository that has all the API types for Rancher 2.x. API Framework | https://github.com/rancher/norman | This repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources. -User Interface | https://github.com/rancher/ui | This repository is the source of the UI. +User Interface | https://github.com/rancher/dashboard/ | This repository is the source of the Dashboard UI. (Rancher) Docker Machine | https://github.com/rancher/machine | This repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the `docker/machine` repository. machine-package | https://github.com/rancher/machine-package | This repository is used to build the Rancher Docker Machine binary. kontainer-engine | https://github.com/rancher/kontainer-engine | This repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters. @@ -36,7 +36,7 @@ loglevel repository | https://github.com/rancher/loglevel | This repository is t To see all libraries/projects used in Rancher, see the [`go.mod` file](https://github.com/rancher/rancher/blob/master/go.mod) in the `rancher/rancher` repository. -![Rancher diagram]({{}}/img/rancher/ranchercomponentsdiagram.svg)
+![Rancher diagram]({{}}/img/rancher/ranchercomponentsdiagram-2.6.svg)
Rancher components used for provisioning/managing Kubernetes clusters. # Building diff --git a/content/rancher/v2.6/en/helm-charts/_index.md b/content/rancher/v2.6/en/helm-charts/_index.md index d225e2f5854..aab00dd91dd 100644 --- a/content/rancher/v2.6/en/helm-charts/_index.md +++ b/content/rancher/v2.6/en/helm-charts/_index.md @@ -9,7 +9,7 @@ In this section, you'll learn how to manage Helm chart repositories and applicat Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts was implemented. The changes are centered around the major version of the charts and the +up annotation for upstream charts, where applicable. -**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps & Marketplace** charts are also upgraded to the correct release line for the chart. +**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps & Marketplace** charts are also upgraded to the correct release line for the chart. >**Note:** Any major versions that are less than the ones mentioned in the table below are meant for 2.5 and below only. For example, you are advised to not use <100.x.x versions of Monitoring in 2.6.x+. @@ -18,27 +18,28 @@ Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts w | **Name** | **Supported Minimum Version** | **Supported Maximum Version** | | ---------------- | ------------ | ------------ | | external-ip-webhook | 100.0.0+up1.0.0 | 100.0.1+up1.0.1 | -| harvester-cloud-provider | 100.0.0+up0.1.8 | 100.0.0+up0.1.8 | -| harvester-csi-driver | 100.0.0+up0.1.9 | 100.0.0+up0.1.9 | -| rancher-alerting-drivers | 100.0.0 | 100.0.1 | -| rancher-backups | 2.0.0 | 2.1.0 | -| rancher-cis-benchmark | 2.0.0 | 2.0.2 | -| rancher-gatekeeper | 100.0.0+up3.5.1 | 100.0.1+up3.6.0 | -| rancher-istio | 100.0.0+up1.10.4 | 100.1.0+up1.11.4 | -| rancher-logging | 100.0.0+up3.12.0 | 100.0.1+up3.15.0 | -| rancher-longhorn | 100.0.0+up1.1.2 | 100.1.1+up1.2.3 | +| harvester-cloud-provider | 100.0.2+up0.1.12 | 100.0.2+up0.1.12 | +| harvester-csi-driver | 100.0.2+up0.1.11 | 100.0.2+up0.1.11 | +| rancher-alerting-drivers | 100.0.0 | 100.0.2 | +| rancher-backup | 2.0.1 | 2.1.2 | +| rancher-cis-benchmark | 2.0.1 | 2.0.4 | +| rancher-gatekeeper | 100.0.0+up3.6.0 | 100.1.0+up3.7.1 | +| rancher-istio | 100.0.0+up1.10.4 | 100.2.0+up1.12.6 | +| rancher-logging | 100.0.0+up3.12.0 | 100.1.2+up3.17.4 | +| rancher-longhorn | 100.0.0+up1.1.2 | 100.1.1+up1.2.3 | | rancher-monitoring | 100.0.0+up16.6.0 | 100.1.0+up19.0.3 -| rancher-sriov (experimental) | 100.0.0+up0.1.0 | 100.0.1+up0.1.0 | -| rancher-vsphere-cpi | 100.0.0 | 100.1.0+up1.0.100 -| rancher-vsphere-csi | 100.0.0 | 100.1.0+up2.3.0 | -| rancher-wins-upgrader | 100.0.0+up0.0.1 | 100.0.0+up0.0.1 | +| rancher-sriov (experimental) | 100.0.0+up0.1.0 | 100.0.3+up0.1.0 | +| rancher-vsphere-cpi | 100.3.0+up1.2.1 | 100.3.0+up1.2.1 | +| rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 | +| rancher-wins-upgrader | 0.0.100 | 100.0.0+up0.0.1 | +| neuvector | 100.0.0+up2.2.0 | 100.0.0+up2.2.0 |
**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also. - As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it. -- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. +- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release. ### Charts @@ -75,7 +76,7 @@ To add a private CA for Helm Chart repositories: ``` -- **Git-based chart repositories**: It is not currently possible to add a private CA. For git-based chart repositories with a certificate signed by a private CA, you must disable TLS verification. Click **Edit YAML** for the chart repo and add the key/value pair as follows: +- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:
``` [...] spec: @@ -85,10 +86,11 @@ To add a private CA for Helm Chart repositories: nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4= [...] ``` - + + > **Note:** Helm chart repositories with authentication > -> As of Rancher v2.6.3, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. +> As of Rancher v2.6.3, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL. > > To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`. > @@ -115,7 +117,7 @@ After installing a chart, you can find it in the _"Installed Apps"_ tab. In this Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information. > If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can: -> +> > * use the default upgrade option ( i.e do not use _"--force"_ option ) > * uninstall the existing chart and install the upgraded chart > * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade @@ -128,4 +130,8 @@ If you have a legacy app installed and want to upgrade it: - The legacy [feature flag]({{}}/rancher/v2.6/en/installation/resources/feature-flags/) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading) - You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps** -- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there \ No newline at end of file +- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there + +### Limitations + +[Dashboard apps or Rancher feature charts](../helm-charts/) **cannot** be installed using the Rancher CLI. diff --git a/content/rancher/v2.6/en/installation/requirements/_index.md b/content/rancher/v2.6/en/installation/requirements/_index.md index c60d529b881..f515e688580 100644 --- a/content/rancher/v2.6/en/installation/requirements/_index.md +++ b/content/rancher/v2.6/en/installation/requirements/_index.md @@ -68,7 +68,7 @@ net.bridge.bridge-nf-call-iptables=1 For the container runtime, K3s should work with any modern version of Docker or containerd. -Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. +Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/) To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. If you are installing Rancher on a K3s cluster with **Raspbian Buster**, follow [these steps]({{}}/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables. @@ -82,8 +82,6 @@ For details on which OS versions were tested with RKE2, refer to the [support ma Docker is not required for RKE2 installs. -The Ingress should be deployed as DaemonSet to ensure your load balancer can successfully route traffic to all nodes. Currently, RKE2 deploys nginx-ingress as a deployment by default, so you will need to deploy it as a DaemonSet by following [these steps.]({{}}/rancher/v2.6/en/installation/resources/k8s-tutorials/ha-rke2/#5-configure-nginx-to-be-a-daemonset) - ### Installing Docker Docker is required for Helm chart installs, and it can be installed by following the steps in the official [Docker documentation.](https://docs.docker.com/) Rancher also provides [scripts]({{}}/rancher/v2.6/en/installation/requirements/installing-docker) to install Docker with one command. @@ -110,7 +108,7 @@ These requirements apply to RKE Kubernetes clusters, as well as to hosted Kubern | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. ### K3s Kubernetes @@ -124,7 +122,7 @@ These CPU and memory requirements apply to each host in a [K3s Kubernetes cluste | X-Large | Up to 1000 | Up to 10,000 | 16 | 64 GB | 2 cores, 4 GB + 1000 IOPS | | XX-Large | Up to 2000 | Up to 20,000 | 32 | 128 GB | 2 cores, 4 GB + 1000 IOPS | -[Contact Rancher](https://rancher.com/contact/) for more than 2000 clusters and/or 20,000 nodes. +Every use case and environment is different. Please [contact Rancher](https://rancher.com/contact/) to review yours. ### RKE2 Kubernetes diff --git a/content/rancher/v2.6/en/installation/resources/feature-flags/_index.md b/content/rancher/v2.6/en/installation/resources/feature-flags/_index.md index a1f92902d3d..25baf0c06a2 100644 --- a/content/rancher/v2.6/en/installation/resources/feature-flags/_index.md +++ b/content/rancher/v2.6/en/installation/resources/feature-flags/_index.md @@ -26,7 +26,7 @@ For example, if you install Rancher, then set a feature flag to true with the Ra The following is a list of the feature flags available in Rancher: - `harvester`: This feature flag is available starting in v2.6.1. It is used to manage access to the Virtualization Management page where users can navigate directly to Harvester clusters and access the Harvester UI. For more information, see [this page]({{}}/rancher/v2.6/en/virtualization-admin/#feature-flag/). -- `rke2`: We have introduced the ability to provision RKE2 clusters as tech preview. By default, this feature flag is enabled, which allows users to attempt to provision these type of clusters. +- `rke2`: Used to enable the ability to provision RKE2 clusters. By default, this feature flag is enabled, which allows users to attempt to provision these type of clusters. - `fleet`: The previous `fleet` feature flag is now required to be enabled as the Fleet capabilities are leveraged within the new provisioning framework. If you had this feature flag disabled in earlier versions, upon upgrading to Rancher v2.6, the flag will automatically be enabled. See this [page]({{}}/rancher/v2.6/en/deploy-across-clusters/fleet) for more information. - `continuous-delivery`: In Rancher v2.5.x, Fleet came with a GitOps feature that could not be disabled separately from Fleet. In Rancher v2.6, the `continuous-delivery` feature flag was introduced to allow the GitOps feature of Fleet to be disabled. For more information, see [this page.](./continuous-delivery). - `legacy`: There are a set of features from previous versions that are slowly being phased out of Rancher for newer iterations of the feature. This is a mix of deprecated features as well as features that will eventually be moved to newer variations in Rancher. By default, this feature flag is disabled for new installations. If you are upgrading from a previous version, this feature flag would be enabled. diff --git a/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md b/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md index 3c01e5f7eaf..057ca0f8c77 100644 --- a/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md +++ b/content/rancher/v2.6/en/installation/resources/update-ca-cert/_index.md @@ -133,7 +133,7 @@ Using a Kubeconfig for each downstream cluster update the environment variable f ``` $ kubectl edit -n cattle-system ds/cattle-node-agent -$ kubectl edit -n cattle-system deployment/cluster-agent +$ kubectl edit -n cattle-system deployment/cattle-cluster-agent ``` ### Method 3: Recreate Rancher agents diff --git a/content/rancher/v2.6/en/monitoring-alerting/configuration/receiver/_index.md b/content/rancher/v2.6/en/monitoring-alerting/configuration/receiver/_index.md index d1754f86d81..3a9daaeb6ce 100644 --- a/content/rancher/v2.6/en/monitoring-alerting/configuration/receiver/_index.md +++ b/content/rancher/v2.6/en/monitoring-alerting/configuration/receiver/_index.md @@ -24,7 +24,6 @@ The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configurati - [Trusted CA for Notifiers](#trusted-ca-for-notifiers) # Creating Receivers in the Rancher UI -_Available as of v2.5.4_ > **Prerequisites:** > @@ -33,11 +32,27 @@ _Available as of v2.5.4_ To create notification receivers in the Rancher UI, -1. Go to the cluster where you want to create receivers. Click **Monitoring** and click **Receiver**. +{{% tabs %}} +{{% tab "Rancher v2.6.5+" %}} + +1. Go to the cluster where you want to create receivers. Click **Monitoring -> Alerting -> AlertManagerConfigs**. +1. Ciick **Create**. +1. Click **Add Receiver**. +1. Enter a **Name** for the receiver. +1. Configure one or more providers for the receiver. For help filling out the forms, refer to the configuration options below. +1. Click **Create**. + +{{% /tab %}} +{{% tab "Rancher before v2.6.5" %}} + +1. Go to the cluster where you want to create receivers. Click **Monitoring** and click **Receiver**. 2. Enter a name for the receiver. 3. Configure one or more providers for the receiver. For help filling out the forms, refer to the configuration options below. 4. Click **Create**. +{{% /tab %}} +{{% /tabs %}} + **Result:** Alerts can be configured to send notifications to the receiver(s). # Receiver Configuration @@ -72,7 +87,7 @@ The custom receiver option can be used to configure any receiver in YAML that ca | Field | Type | Description | |------|--------------|------| | URL | String | Enter your Slack webhook URL. For instructions to create a Slack webhook, see the [Slack documentation.](https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack) | -| Default Channel | String | Enter the name of the channel that you want to send alert notifications in the following format: `#`. | +| Default Channel | String | Enter the name of the channel that you want to send alert notifications in the following format: `#`. | | Proxy URL | String | Proxy for the webhook notifications. | | Enable Send Resolved Alerts | Bool | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | @@ -81,7 +96,7 @@ The custom receiver option can be used to configure any receiver in YAML that ca | Field | Type | Description | |------|--------------|------| | Default Recipient Address | String | The email address that will receive notifications. | -| Enable Send Resolved Alerts | Bool | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | +| Enable Send Resolved Alerts | Bool | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | SMTP options: @@ -100,7 +115,7 @@ SMTP options: | Integration Type | String | `Events API v2` or `Prometheus`. | | Default Integration Key | String | For instructions to get an integration key, see the [PagerDuty documentation.](https://www.pagerduty.com/docs/guides/prometheus-integration-guide/) | | Proxy URL | String | Proxy for the PagerDuty notifications. | -| Enable Send Resolved Alerts | Bool | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | +| Enable Send Resolved Alerts | Bool | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | # Opsgenie @@ -172,7 +187,7 @@ The SMS receiver is not a native receiver and must be enabled before it can be u 1. In the upper left corner, click **☰ > Cluster Management**. 1. On the **Clusters** page, go to the cluster where you want to install `rancher-alerting-drivers` and click **Explore**. -1. In the left navigation bar, click +1. In the left navigation bar, click 1. Click the **Alerting Drivers** app. 1. Click the **Helm Deploy Options** tab 1. Select the **SMS** option and click **Install**. @@ -224,11 +239,11 @@ You can also set up multiple receivers by using the `continue` option for a rout To set up notifications via Slack, the following Alertmanager Config YAML can be placed into the `alertmanager.yaml` key of the Alertmanager Config Secret, where the `api_url` should be updated to use your Webhook URL from Slack: ```yaml -route: +route: group_by: ['job'] group_wait: 30s group_interval: 5m - repeat_interval: 3h + repeat_interval: 3h receiver: 'slack-notifications' receivers: - name: 'slack-notifications' diff --git a/content/rancher/v2.6/en/monitoring-alerting/configuration/route/_index.md b/content/rancher/v2.6/en/monitoring-alerting/configuration/route/_index.md index 4fc0019c79f..4366f20a9a5 100644 --- a/content/rancher/v2.6/en/monitoring-alerting/configuration/route/_index.md +++ b/content/rancher/v2.6/en/monitoring-alerting/configuration/route/_index.md @@ -42,6 +42,21 @@ The route needs to refer to a [receiver](#receiver-configuration) that has alrea ### Grouping +{{% tabs %}} +{{% tab "Rancher v2.6.5+" %}} + +> **Note** As of Rancher v2.6.5 `Group By` now accepts a list of strings instead of key-value pairs. See the [upstream documentation](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#route) for details. + +| Field | Default | Description | +|-------|--------------|---------| +| Group By | N/a | List of labels to group by. Labels must not be repeated (unique list). Special label "..." (aggregate by all possible labels), if provided, must be the only element in the list. | +| Group Wait | 30s | How long to wait to buffer alerts of the same group before sending initially. | +| Group Interval | 5m | How long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent. | +| Repeat Interval | 4h | How long to wait before re-sending a given alert that has already been sent. | + +{{% /tab %}} +{{% tab "Rancher before v2.6.5" %}} + | Field | Default | Description | |-------|--------------|---------| | Group By | N/a | The labels by which incoming alerts are grouped together. For example, `[ group_by: '[' , ... ']' ]` Multiple alerts coming in for labels such as `cluster=A` and `alertname=LatencyHigh` can be batched into a single group. To aggregate by all possible labels, use the special value `'...'` as the sole label name, for example: `group_by: ['...']` Grouping by `...` effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what you want, unless you have a very low alert volume or your upstream notification system performs its own grouping. | @@ -49,6 +64,11 @@ The route needs to refer to a [receiver](#receiver-configuration) that has alrea | Group Interval | 5m | How long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent. | | Repeat Interval | 4h | How long to wait before re-sending a given alert that has already been sent. | +{{% /tab %}} +{{% /tabs %}} + + + ### Matching The **Match** field refers to a set of equality matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs to the Rancher UI, they correspond to the YAML in this format: diff --git a/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/_index.md b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/_index.md new file mode 100644 index 00000000000..cc88321bee4 --- /dev/null +++ b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/_index.md @@ -0,0 +1,83 @@ +--- +title: Prometheus Federator +weight: 7 +--- + +Prometheus Federator, also referred to as Project Monitoring v2, deploys a Helm Project Operator (based on the [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator)), an operator that manages deploying Helm charts each containing a Project Monitoring Stack, where each stack contains: + +- [Prometheus](https://prometheus.io/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) +- [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator)) +- [Grafana](https://github.com/helm/charts/tree/master/stable/grafana) (deployed via an embedded Helm chart) +- Default PrometheusRules and Grafana dashboards based on the collection of community-curated resources from [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus/) +- Default ServiceMonitors that watch the deployed resources + +> **Important** Prometheus Federator is designed to be deployed alongside an existing Prometheus Operator deployment in a cluster that has already installed the Prometheus Operator CRDs. + +## How does the operator work? + +1. On deploying this chart, users can create ProjectHelmCharts CRs with `spec.helmApiVersion` set to `monitoring.cattle.io/v1alpha1` (also known as "Project Monitors" in the Rancher UI) in a **Project Registration Namespace (`cattle-project-`)**. +2. On seeing each ProjectHelmChartCR, the operator will automatically deploy a Project Prometheus stack on the Project Owner's behalf in the **Project Release Namespace (`cattle-project--monitoring`)** based on a HelmChart CR and a HelmRelease CR automatically created by the ProjectHelmChart controller in the **Operator / System Namespace**. +3. RBAC will automatically be assigned in the Project Release Namespace to allow users to view the Prometheus, Alertmanager, and Grafana UIs of the Project Monitoring Stack deployed; this will be based on RBAC defined on the Project Registration Namespace against the [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles). For more information, see the section on [configuring RBAC](./rbac/). + +### What is a Project? + +In Prometheus Federator, a Project is a group of namespaces that can be identified by a `metav1.LabelSelector`. By default, the label used to identify projects is `field.cattle.io/projectId`, the label used to identify namespaces that are contained within a given Rancher Project. + +### Configuring the Helm release created by a ProjectHelmChart + +The `spec.values` of this ProjectHelmChart's resources will correspond to the `values.yaml` override to be supplied to the underlying Helm chart deployed by the operator on the user's behalf; to see the underlying chart's `values.yaml` spec, either: + +- View the chart's definition located at [`rancher/prometheus-federator` under `charts/rancher-project-monitoring`](https://github.com/rancher/prometheus-federator/blob/main/charts/rancher-project-monitoring) (where the chart version will be tied to the version of this operator). +- Look for the ConfigMap named `monitoring.cattle.io.v1alpha1` that is automatically created in each Project Registration Namespace, which will contain both the `values.yaml` and `questions.yaml` that was used to configure the chart (which was embedded directly into the `prometheus-federator` binary). + +### Namespaces + +As a Project Operator based on [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator), Prometheus Federator has three different classifications of namespaces that the operator looks out for: + +1. **Operator / System Namespace**: The namespace that the operator is deployed into (e.g., `cattle-monitoring-system`). This namespace will contain all HelmCharts and HelmReleases for all ProjectHelmCharts watched by this operator. **Only Cluster Admins should have access to this namespace.** +2. **Project Registration Namespace (`cattle-project-`)**: The set of namespaces that the operator watches for ProjectHelmCharts within. The RoleBindings and ClusterRoleBindings that apply to this namespace will also be the source of truth for the auto-assigned RBAC created in the Project Release Namespace. For details, refer to the [RBAC page](./rbac/). **Project Owners (admin), Project Members (edit), and Read-Only Members (view) should have access to this namespace.** + + > **Note:** Project Registration Namespaces will be auto-generated by the operator and imported into the Project it is tied to if `.Values.global.cattle.projectLabel` is provided, which is set to `field.cattle.io/projectId` by default. This indicates that a Project Registration Namespace should be created by the operator if at least one namespace is observed with that label. The operator will not let these namespaces be deleted unless either all namespaces with that label are gone (e.g., this is the last namespace in that project, in which case the namespace will be marked with the label `"helm.cattle.io/helm-project-operator-orphaned": "true"`, which signals that it can be deleted), or it is no longer watching that project because the project ID was provided under `.Values.helmProjectOperator.otherSystemProjectLabelValues`, which serves as a denylist for Projects. These namespaces will also never be auto-deleted to avoid destroying user data; it is recommended that users clean up these namespaces manually if desired on creating or deleting a project. + + > **Note:** If `.Values.global.cattle.projectLabel` is not provided, the Operator / System Namespace will also be the Project Registration Namespace. +3. **Project Release Namespace (`cattle-project--monitoring`):** The set of namespaces that the operator deploys Project Monitoring Stacks within on behalf of a ProjectHelmChart; the operator will also automatically assign RBAC to Roles created in this namespace by the Project Monitoring Stack based on bindings found in the Project Registration Namespace. **Only Cluster Admins should have access to this namespace; Project Owners (admin), Project Members (edit), and Read-Only Members (view) will be assigned limited access to this namespace by the deployed Helm Chart and Prometheus Federator.** + + > **Note:** Project Release Namespaces are automatically deployed and imported into the project whose ID is specified under `.Values.helmProjectOperator.projectReleaseNamespaces.labelValue`, which defaults to the value of `.Values.global.cattle.systemProjectId` if not specified, whenever a ProjectHelmChart is specified in a Project Registration Namespace. + + > **Note:** Project Release Namespaces follow the same orphaning conventions as Project Registration Namespaces (see note above). + + > **Note:** If `.Values.projectReleaseNamespaces.enabled` is false, the Project Release Namespace will be the same as the Project Registration Namespace. + +### Helm Resources (HelmChart, HelmRelease) + +On deploying a ProjectHelmChart, the Prometheus Federator will automatically create and manage two child custom resources that manage the underlying Helm resources in turn: + +- A HelmChart CR (managed via an embedded [k3s-io/helm-contoller](https://github.com/k3s-io/helm-controller) in the operator): This custom resource automatically creates a Job in the same namespace that triggers a `helm install`, `helm upgrade`, or `helm uninstall` depending on the change applied to the HelmChart CR. This CR is automatically updated on changes to the ProjectHelmChart (e.g., modifying the values.yaml) or changes to the underlying Project definition (e.g., adding or removing namespaces from a project). + +> **Important:** If a ProjectHelmChart is not deploying or updating the underlying Project Monitoring Stack for some reason, the Job created by this resource in the Operator / System namespace should be the first place you check to see if there's something wrong with the Helm operation. However, this is generally only accessible by a **Cluster Admin.** + +- A HelmRelease CR (managed via an embedded [rancher/helm-locker](https://github.com/rancher/helm-locker) in the operator): This custom resource automatically locks a deployed Helm release in place and automatically overwrites updates to underlying resources unless the change happens via a Helm operation (`helm install`, `helm upgrade`, or `helm uninstall` performed by the HelmChart CR). + +> **Note:** HelmRelease CRs emit Kubernetes Events that detect when an underlying Helm release is being modified and locks it back to place. To view these events, you can use `kubectl describe helmrelease -n `; you can also view the logs on this operator to see when changes are detected and which resources modifications were attempted on. + +Both of these resources are created for all Helm charts in the Operator / System namespaces to avoid escalation of privileges to underprivileged users. + +### Advanced Helm Project Operator Configuration + +For more information on advanced configurations, refer to [this page](https://github.com/rancher/prometheus-federator/blob/main/charts/prometheus-federator/0.0.1/README.md#advanced-helm-project-operator-configuration). + + + +### Prometheus Federator on the Local Cluster + +Prometheus Federator is a resource intensive application. Installing it to the local cluster is possible, but **not recommended**. \ No newline at end of file diff --git a/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/customizing-grafana/_index.md b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/customizing-grafana/_index.md new file mode 100644 index 00000000000..f5cc1e5653d --- /dev/null +++ b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/customizing-grafana/_index.md @@ -0,0 +1,8 @@ +--- +title: Customizing Grafana Dashboards +weight: 3 +--- + +Grafana dashboards are customized the same way whether it's for rancher-monitoring or for Prometheus Federator. + +For instructions, refer to [this page](../../../guides/customize-grafana/). \ No newline at end of file diff --git a/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/_index.md b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/_index.md new file mode 100644 index 00000000000..ae4ff801de2 --- /dev/null +++ b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/enable-prom-fed/_index.md @@ -0,0 +1,62 @@ +--- +title: Enable Prometheus Federator +weight: 1 +--- + +- [Requirements](#requirements) +- [Install the Prometheus Federator Application](#install-the-prometheus-federator-application) + +# Requirements + +By default, Prometheus Federator is configured and intended to be deployed alongside [rancher-monitoring](https://rancher.com/docs/rancher/v2.6/en/monitoring-alerting/), which deploys Prometheus Operator alongside a Cluster Prometheus that each Project Monitoring Stack is configured to federate namespace-scoped metrics from by default. + +For instructions on installing rancher-monitoring, refer to [this page](../../../guides/enable-monitoring/). + +The default configuration should already be compatible with your rancher-monitoring stack. However, to optimize the security and usability of Prometheus Federator in your cluster, we recommend making these additional configurations to rancher-monitoring: + +- [Ensure the cattle-monitoring-system namespace is placed into the System Project](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster). +- [Configure rancher-monitoring to only watch for resources created by the Helm chart itself](#configure-rancher-monitoring-to-only-watch-for-resources-created-by-the-helm-chart-itself). +- [Increase the CPU / memory limits of the Cluster Prometheus](#increase-the-cpu--memory-limits-of-the-cluster-prometheus). + +## Ensure the cattle-monitoring-system namespace is placed into the System Project (or a similarly locked down Project that has access to other Projects in the cluster) + +Prometheus Operator's security model expects that the namespace it is deployed into (e.g., `cattle-monitoring-system`) has limited access for anyone except Cluster Admins to avoid privilege escalation via execing into Pods (such as the Jobs executing Helm operations). In addition, deploying Prometheus Federator and all Project Prometheus stacks into the System Project ensures that each Project Prometheus is able to reach out to scrape workloads across all Projects, even if Network Policies are defined via Project Network Isolation. It also provides limited access for Project Owners, Project Members, and other users so that they're unable to access data that they shouldn't have access to (i.e., being allowed to exec into pods, set up the ability to scrape namespaces outside of a given Project, etc.). + +## Configure rancher-monitoring to only watch for resources created by the Helm chart itself + +Since each Project Monitoring Stack will watch the other namespaces and collect additional custom workload metrics or dashboards already, it's recommended to configure the following settings on all selectors to ensure that the Cluster Prometheus Stack only monitors resources created by the Helm Chart itself: + +``` +matchLabels: + release: "rancher-monitoring" +``` + +The following selector fields are recommended to have this value: +- `.Values.alertmanager.alertmanagerSpec.alertmanagerConfigSelector` +- `.Values.prometheus.prometheusSpec.serviceMonitorSelector` +- `.Values.prometheus.prometheusSpec.podMonitorSelector` +- `.Values.prometheus.prometheusSpec.ruleSelector` +- `.Values.prometheus.prometheusSpec.probeSelector` + +Once this setting is turned on, you can always create ServiceMonitors or PodMonitors that are picked up by the Cluster Prometheus by adding the label `release: "rancher-monitoring"` to them, in which case they will be ignored by Project Monitoring Stacks automatically by default, even if the namespace in which those ServiceMonitors or PodMonitors reside in are not system namespaces. + +> Note: If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain `cattle-monitoring-system` and `cattle-dashboards`, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the `default` namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn `.Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true` to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace. + +## Increase the CPU / memory limits of the Cluster Prometheus + +Depending on a cluster's setup, it's generally recommended to give a large amount of dedicated memory to the Cluster Prometheus to avoid restarts due to out-of-memory errors (OOMKilled) usually caused by churn created in the cluster that causes a large number of high cardinality metrics to be generated and ingested by Prometheus within one block of time. This is one of the reasons why the default Rancher Monitoring stack expects around 4GB of RAM to be able to operate in a normal-sized cluster. However, when introducing Project Monitoring Stacks that are all sending `/federate` requests to the same Cluster Prometheus and are reliant on the Cluster Prometheus being "up" to federate that system data on their namespaces, it's even more important that the Cluster Prometheus has an ample amount of CPU / memory assigned to it to prevent an outage that can cause data gaps across all Project Prometheis in the cluster. + +> Note: There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup. + +# Install the Prometheus Federator Application + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you want to install Prometheus Federator and click **Explore**. +1. Click **Apps -> Charts**. +1. Click the **Prometheus Federator** chart. +1. Click **Install**. +1. On the **Metadata** page, click **Next**. +1. In the **Project Release Namespace Project ID** field, the `System Project` is used as the default but can be overridden with another project with similarly [limited access](#ensure-the-cattle-monitoring-system-namespace-is-placed-into-the-system-project-or-a-similarly-locked-down-project-that-has-access-to-other-projects-in-the-cluster). + +### Display CPU and Memory Metrics for a Workload + +Displaying CPU and memory metrics with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../../../guides/monitoring-workloads/_index.md#display-cpu-and-memory-metrics-for-a-workload). + +### Setting up Metrics Beyond CPU and Memory + +Setting up metrics beyond CPU and memory with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer [here](../../../guides/monitoring-workloads/_index.md#setting-up-metrics-beyond-cpu-and-memory). + + \ No newline at end of file diff --git a/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/uninstall-prom-fed/_index.md b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/uninstall-prom-fed/_index.md new file mode 100644 index 00000000000..2db6cdda414 --- /dev/null +++ b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/guides/uninstall-prom-fed/_index.md @@ -0,0 +1,14 @@ +--- +title: Uninstall Prometheus Federator +weight: 2 +--- + +1. Click **☰ > Cluster Management**. +1. Go to the cluster that you created and click **Explore**. +1. In the left navigation bar, click **Apps & Marketplace**. +1. Click **Installed Apps**. +1. Go to the `cattle-monitoring-system` namespace and check the boxes for `rancher-monitoring-crd` and `rancher-monitoring`. +1. Click **Delete**. +1. Confirm **Delete**. + +**Result:** `prometheus-federator` is uninstalled. diff --git a/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/rbac/_index.md b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/rbac/_index.md new file mode 100644 index 00000000000..d656246d982 --- /dev/null +++ b/content/rancher/v2.6/en/monitoring-alerting/prometheus-federator/rbac/_index.md @@ -0,0 +1,29 @@ +--- +title: Role-Based Access Control +shortTitle: RBAC +weight: 2 +--- + +This section describes the expectations for Role-Based Access Control (RBAC) for Prometheus Federator. + +As described in the section on [namespaces](../_index.md#namespaces), Prometheus Federator expects that Project Owners, Project Members, and other users in the cluster with Project-level permissions (e.g. permissions in a certain set of namespaces identified by a single label selector) have minimal permissions in any namespaces except the Project Registration Namespace (which is imported into the project by default) and those that already comprise their projects. Therefore, in order to allow Project Owners to assign specific chart permissions to other users in their Project namespaces, the Helm Project Operator will automatically watch the following bindings: + +- ClusterRoleBindings +- RoleBindings in the Project Release Namespace + +On observing a change to one of those types of bindings, the Helm Project Operator will check whether the `roleRef` that the the binding points to matches a ClusterRole with the name provided under: + +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.admin` +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.edit` +- `helmProjectOperator.releaseRoleBindings.clusterRoleRefs.view` + +By default, these roleRefs will correspond to `admin`, `edit`, and `view` respectively, which are the [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles). + +> **Note** For Rancher RBAC users, these [default Kubernetes user-facing roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) directly correlate to the `Project Owner`, `Project Member`, and `Read-Only` default Project Role Templates. + +If the `roleRef` matches, the Helm Project Operator will filter the `subjects` of the binding for all Users and Groups and use that to automatically construct a RoleBinding for each Role in the Project Release Namespace with the same name as the role and the following labels: + +- `helm.cattle.io/project-helm-chart-role: {{ .Release.Name }}` +- `helm.cattle.io/project-helm-chart-role-aggregate-from: ` + +By default, `rancher-project-monitoring`, the underlying chart deployed by Prometheus Federator, creates three default Roles per Project Release Namespace that provide `admin`, `edit`, and `view` users to permissions to view the Prometheus, Alertmanager, and Grafana UIs of the Project Monitoring Stack to provide least privilege. However, if a Cluster Admin would like to assign additional permissions to certain users, they can either directly assign RoleBindings in the Project Release Namespace to certain users or create Roles with the above two labels on them to allow Project Owners to control assigning those RBAC roles to users in their Project Registration namespaces. \ No newline at end of file diff --git a/content/rancher/v2.6/en/neuvector-integration/_index.md b/content/rancher/v2.6/en/neuvector-integration/_index.md new file mode 100644 index 00000000000..1c58d6e200a --- /dev/null +++ b/content/rancher/v2.6/en/neuvector-integration/_index.md @@ -0,0 +1,120 @@ +--- +title: NeuVector Integration +weight: 22 +--- + +### NeuVector Integration in Rancher + +New in Rancher v2.6.5, [NeuVector 5.x](https://open-docs.neuvector.com/) is an open-source container-centric security platform that is now integrated into Rancher. NeuVector offers real-time compliance, visibility, and protection for critical applications and data during runtime. NeuVector provides a firewall, container process/file system monitoring, security auditing with CIS benchmarks, and vulnerability scanning. For more information on Rancher security, please see the [security documentation]({{}}/rancher/v2.6/en/security/). + +NeuVector can be enabled through a Helm chart that may be installed either through **Apps & Marketplace** or through the **Cluster Tools** button in the Rancher UI. Once the Helm chart is installed, users can easily [deploy and manage NeuVector clusters within Rancher](https://open-docs.neuvector.com/deploying/rancher#deploy-and-manage-neuvector-through-rancher-apps-marketplace). + +### Installing NeuVector with Rancher + +The Harvester Helm Chart is used to manage access to the NeuVector UI in Rancher where users can navigate directly to deploy and manage their NeuVector clusters. + +**To navigate to and install the NeuVector chart through Apps & Marketplace:** + +1. Click **☰ > Cluster Management**. +1. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click **Explore**. +1. Go to **Apps & Marketplace > Charts**, and install **NeuVector** from the chart repo. +1. Different cluster types require different container runtimes. When configuring Helm chart values, go to the **Container Runtime** section, and select your runtime in accordance with the cluster type. Finally, click **Install** again. + +Some examples are as follows: + + - RKE1: `docker` + - K3s and RKE2: `k3scontainerd` + - AKS: `containerd` for v1.19 and up + - EKS: `docker` for v1.22 and below; `containerd` for v1.23 and up + - GKE: `containerd` (see the [Google docs](https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd) for more) + + >**Note:** Only one container runtime engine may be selected at a time during installation. + +**To navigate to and install the NeuVector chart through Cluster Tools:** + +1. Click **☰ > Cluster Management**. +1. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click **Explore**. +1. Click on **Cluster Tools** at the bottom of the left navigation bar. +1. Repeat step 4 above to select your container runtime accordingly, then click **Install** again. + +### Accessing NeuVector from the Rancher UI + +1. Navigate to the cluster explorer of the cluster where NeuVector is installed. In the left navigation bar, click **NeuVector**. +1. Click the external link to go to the NeuVector UI. Once the link is selected, users must accept the `END USER LICENSE AGREEMENT` to access the NeuVector UI. + +### Uninstalling NeuVector from the Rancher UI + +**To uninstall from Apps & Marketplace:** + +1. Click **☰ > Cluster Management**. +1. Under **Apps & Marketplace**, click **Installed Apps**. +1. Under `cattle-neuvector-system`, select both the NeuVector app (and the associated CRD if desired), then click **Delete**. + +**To uninstall from Cluster Tools:** + +1. Click **☰ > Cluster Management**. +1. Click on **Cluster Tools** at the bottom-left of the screen, then click on the trash can icon under the NeuVector chart. Select `Delete the CRD associated with this app` if desired, then click **Delete**. + +### GitHub Repository + +The NeuVector project is available [here](https://github.com/neuvector/neuvector). + +### Documentation + +The NeuVector documentation is [here](https://open-docs.neuvector.com/). + +### Architecture + +The NeuVector security solution contains four types of security containers: Controllers, Enforcers, Managers, and Scanners. A special container called an All-in-One is also provided to combine the Controller, Enforcer, and Manager functions all in one container, primarily for Docker-native deployments. There is also an Updater which, when run, will update the CVE database. + +- **Controller:** Manages the NeuVector Enforcer container; provides REST APIs for the management console. +- **Enforcer:** Enforces security policies. +- **Manager:** Provides a web-UI and CLI console to manage the NeuVector platform. +- **All-in-One:** Includes the Controller, Enforcer, and Manager. +- **Scanner:** Performs the vulnerability and compliance scanning for images, containers, and nodes. +- **Updater:** Updates the CVE database for Neuvector (when run); redeploys scanner pods. + +
**NeuVector Security Containers:**
+![NeuVector Security Containers]({{}}/img/rancher/neuvector-security-containers.png) + +
**NeuVector Architecture:**
+![NeuVector Architecture]({{}}/img/rancher/neuvector-architecture.png) + +To learn more about NeuVector's architecture, please refer [here](https://open-docs.neuvector.com/basics/overview#architecture). + +### CPU and Memory Allocations + +Below are the minimum recommended computing resources for the NeuVector chart installation in a default deployment. Note that the resource limit is not set. + +| Container | CPU - Request | Memory - Request | +|------------|--------|---------| +| Controller | 3 (1GB 1vCPU needed per controller) | * +| Enforcer | On all nodes (500MB .5vCPU) | 1GB +| Manager | 1 (500MB .5vCPU) | * +| Scanner | 3 (100MB .5vCPU) | * + +\* Minimum 1GB of memory total required for Controller, Manager, and Scanner containers combined. + + +### Support Limitations + +* Only admins and cluster owners are currently supported. + +* Fleet multi-cluster deployment is not supported. + +* NeuVector is not supported on a Windows cluster. + +* NeuVector installation is not supported on hardened clusters. + +* NeuVector installation is not supported on SELinux clusters. + +* NeuVector installation is not supported on clusters in an air-gapped environment. + +### Other Limitations + +* Currently, NeuVector feature chart installation fails when a NeuVector partner chart already exists. To work around this issue, uninstall the NeuVector partner chart and reinstall the NeuVector feature chart. + +* Sometimes when the controllers are not ready, the NeuVector UI is not accessible from the Rancher UI. During this time, controllers will try to restart, and it takes a few minutes for the controllers to be active. + +* Container runtime is not auto-detected for different cluster types when installing the NeuVector chart. To work around this, you can specify the runtime manually. + diff --git a/content/rancher/v2.6/en/security/_index.md b/content/rancher/v2.6/en/security/_index.md index 0cd5e3dcaf4..8b782b613c5 100644 --- a/content/rancher/v2.6/en/security/_index.md +++ b/content/rancher/v2.6/en/security/_index.md @@ -24,6 +24,7 @@ Security is at the heart of all Rancher features. From integrating with all the On this page, we provide security related documentation along with resources to help you secure your Rancher installation and your downstream Kubernetes clusters: +- [NeuVector Integration with Rancher](#neuvector-integration-with-rancher) - [Running a CIS security scan on a Kubernetes cluster](#running-a-cis-security-scan-on-a-kubernetes-cluster) - [SELinux RPM](#selinux-rpm) - [Guide to hardening Rancher installations](#rancher-hardening-guide) @@ -32,6 +33,12 @@ On this page, we provide security related documentation along with resources to - [Rancher Security Advisories and CVEs](#rancher-security-advisories-and-cves) - [Kubernetes Security Best Practices](#kubernetes-security-best-practices) +### NeuVector Integration with Rancher + +_New in v2.6.5_ + +NeuVector is an open-source, container-focused security application that is now integrated into Rancher. NeuVector provides production security, DevOps vulnerability protection, and a container firewall, et al. Please see the [Rancher docs]({{}}/rancher/v2.6/en/neuvector-integration) and the [NeuVector docs](https://open-docs.neuvector.com/) for more information. + ### Running a CIS Security Scan on a Kubernetes Cluster Rancher leverages [kube-bench](https://github.com/aquasecurity/kube-bench) to run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the [CIS](https://www.cisecurity.org/cis-benchmarks/) (Center for Internet Security) Kubernetes Benchmark. diff --git a/static/img/rancher/neuvector-architecture.png b/static/img/rancher/neuvector-architecture.png new file mode 100644 index 00000000000..d690a1af3b9 Binary files /dev/null and b/static/img/rancher/neuvector-architecture.png differ diff --git a/static/img/rancher/neuvector-security-containers.png b/static/img/rancher/neuvector-security-containers.png new file mode 100644 index 00000000000..1750a2444e6 Binary files /dev/null and b/static/img/rancher/neuvector-security-containers.png differ diff --git a/static/img/rancher/ranchercomponentsdiagram-2.6.svg b/static/img/rancher/ranchercomponentsdiagram-2.6.svg new file mode 100644 index 00000000000..f63b84b3e75 --- /dev/null +++ b/static/img/rancher/ranchercomponentsdiagram-2.6.svg @@ -0,0 +1,2 @@ + +
Rancher 2.x
[Not supported by viewer]
Importing Kubernetes Clusters
<b>Importing Kubernetes Clusters</b>

  • Any Kubernetes cluster                      
[Not supported by viewer]
Provisioning Kubernetes Clusters
<b>Provisioning Kubernetes Clusters</b>
Rancher
<b>Rancher</b>
Rancher Launched Kubernetes
  • Nodes Hosted in an Infrastructure Provider
    • Amazon EC2
    • DigitalOcean
    • Azure
    • vSphere
    • Any (pluggable)
[Not supported by viewer]
Rancher Agents
<b>Rancher Agents</b>
Provisioning
<b>Provisioning</b>
API Framework & Types
[Not supported by viewer]
Utilities
[Not supported by viewer]
Rancher Server
https://github.com/rancher/rancher
Rancher Server<br>https://github.com/rancher/rancher<br>
RKE
https://github.com/rancher/rke
RKE<br>https://github.com/rancher/rke<br>
docker-machine
https://github.com/rancher/machine
docker-machine<br>https://github.com/rancher/machine<br>
Rancher CLI
https://github.com/rancher/cli
Rancher CLI<br>https://github.com/rancher/cli<br>
Norman
https://github.com/rancher/norman
Norman<br>https://github.com/rancher/norman<br>
Types
https://github.com/rancher/types
Types<br>https://github.com/rancher/types<br>
cattle-cluster-agent

cattle-cluster-agent<br><br>
cattle-node-agent
cattle-node-agent<br>
Rancher Launched Kubernetes
  • Creating a Cluster with Custom Nodes
[Not supported by viewer]
Rancher Agents
<b>Rancher Agents</b>
Provisioning
<b>Provisioning</b>
RKE
https://github.com/rancher/rke
RKE<br>https://github.com/rancher/rke<br>
cattle-cluster-agent

cattle-cluster-agent<br><br>
cattle-node-agent
cattle-node-agent<br>
Hosted Kubernetes Providers
  • Google Kubernetes Engine (GKE)
  • Amazon Elastic Container Service for Kubernetes (EKS)
  • Azure Kubernetes Service (AKS)
[Not supported by viewer]
Rancher Agents
<b>Rancher Agents</b>
Provisioning
<b>Provisioning</b>
kontainer-engine
https://github.com/rancher/
kontainer-engine
[Not supported by viewer]
cattle-cluster-agent

cattle-cluster-agent<br><br>
cattle-node-agent
cattle-node-agent<br>
Rancher Agents
<b>Rancher Agents</b>
cattle-cluster-agent

cattle-cluster-agent<br><br>
cattle-node-agent
cattle-node-agent<br>
User Interface
[Not supported by viewer]
Rancher Dashboard UI
https://github.com/rancher/dashboard
Rancher Dashboard UI<br>https://github.com/rancher/dashboard<br>
Rancher API UI
https://github.com/rancher/api-ui
Rancher API UI<br>https://github.com/rancher/api-ui<br>
Catalog Applications
https://github.com/rancher/helm
Catalog Applications<br>https://github.com/rancher/helm<br> \ No newline at end of file