diff --git a/content/_index.html b/content/_index.html index 209d77f70cb..fe9ce90017d 100644 --- a/content/_index.html +++ b/content/_index.html @@ -101,8 +101,8 @@ card-item">

- 2.x - Rancher 2.x + 2.5 + Rancher 2.5

@@ -110,11 +110,30 @@

Rancher manages all of your Kubernetes clusters everywhere, unifies them under centralized RBAC, monitors them and lets you easily deploy and manage workloads through an intuitive user interface.

- - - + Rancher v2.5 +
+
+ +
+
+

+ 2.0-2.4 + Rancher 2.0-2.4 +

+ +
+ +

Rancher manages all of your Kubernetes clusters everywhere, unifies them under centralized RBAC, monitors them and lets you easily deploy and manage workloads through an intuitive user interface.

+ +
+ Rancher v2.0-v2.4
diff --git a/content/rancher/v2.5/en/cluster-admin/editing-clusters/_index.md b/content/rancher/v2.5/en/cluster-admin/editing-clusters/_index.md index 011d4e92b1f..610282c58f8 100644 --- a/content/rancher/v2.5/en/cluster-admin/editing-clusters/_index.md +++ b/content/rancher/v2.5/en/cluster-admin/editing-clusters/_index.md @@ -34,7 +34,7 @@ Option | Description | ---------|----------| Kubernetes Version | The version of Kubernetes installed on each cluster node. For more detail, see [Upgrading Kubernetes]({{}}/rancher/v2.5/en/cluster-admin/upgrading-kubernetes). | Network Provider | The \container networking interface (CNI) that powers networking for your cluster.

**Note:** You can only choose this option while provisioning your cluster. It cannot be edited later. | - Project Network Isolation | If you're using the Canal network provider, you can choose whether to enable or disable inter-project communication. | + Project Network Isolation | If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication. Before Rancher v2.5.8, project network isolation is only available if you are using the Canal network plugin for RKE. In v2.5.8+, project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.| Nginx Ingress | If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster. | Metrics Server Monitoring | Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal. | Pod Security Policy Support | Enables [pod security policies]({{}}/rancher/v2.5/en/admin-settings/pod-security-policies/) for the cluster. After enabling this option, choose a policy using the **Default Pod Security Policy** drop-down. | diff --git a/content/rancher/v2.5/en/cluster-admin/projects-and-namespaces/_index.md b/content/rancher/v2.5/en/cluster-admin/projects-and-namespaces/_index.md index dbf7e3cf84f..b495d62f208 100644 --- a/content/rancher/v2.5/en/cluster-admin/projects-and-namespaces/_index.md +++ b/content/rancher/v2.5/en/cluster-admin/projects-and-namespaces/_index.md @@ -106,12 +106,7 @@ The `system` project: - Allows you to add more namespaces or move its namespaces to other projects. - Cannot be deleted because it's required for cluster operations. ->**Note:** In clusters where both: -> -> - The Canal network plug-in is in use. -> - The Project Network Isolation option is enabled. -> ->The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health. +>**Note:** In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health. # Project Authorization diff --git a/content/rancher/v2.5/en/cluster-provisioning/_index.md b/content/rancher/v2.5/en/cluster-provisioning/_index.md index cc063af1adc..3be9c2d0505 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/_index.md @@ -18,6 +18,7 @@ This section covers the following topics: +- [Cluster Management Capabilities by Cluster Type](#cluster-management-capabilities-by-cluster-type) - [Setting up clusters in a hosted Kubernetes provider](#setting-up-clusters-in-a-hosted-kubernetes-provider) - [Launching Kubernetes with Rancher](#launching-kubernetes-with-rancher) - [Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider](#launching-kubernetes-and-provisioning-nodes-in-an-infrastructure-provider) @@ -27,6 +28,8 @@ This section covers the following topics: +### Cluster Management Capabilities by Cluster Type + The following table summarizes the options and settings available for each cluster type: {{% include file="/rancher/v2.5/en/cluster-provisioning/cluster-capabilities-table" %}} diff --git a/content/rancher/v2.5/en/cluster-provisioning/cluster-capabilities-table/index.md b/content/rancher/v2.5/en/cluster-provisioning/cluster-capabilities-table/index.md index 81cbefffc6d..5dd2664c8b7 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/cluster-capabilities-table/index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/cluster-capabilities-table/index.md @@ -1,22 +1,59 @@ --- headless: true --- -| Action | [Rancher launched Kubernetes Clusters]({{}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/) | [Hosted Kubernetes Clusters]({{}}/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/) | [Imported Clusters]({{}}/rancher/v2.5/en/cluster-provisioning/imported-clusters) | -| --- | --- | ---| ---| -| [Using kubectl and a kubeconfig file to Access a Cluster]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/kubectl/) | ✓ | ✓ | ✓ | -| [Managing Cluster Members]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/cluster-members/) | ✓ | ✓ | ✓ | -| [Editing and Upgrading Clusters]({{}}/rancher/v2.5/en/cluster-admin/editing-clusters/) | ✓ | ✓ | * | -| [Managing Nodes]({{}}/rancher/v2.5/en/cluster-admin/nodes) | ✓ | ✓ | ✓ | -| [Managing Persistent Volumes and Storage Classes]({{}}/rancher/v2.5/en/cluster-admin/volumes-and-storage/) | ✓ | ✓ | ✓ | -| [Managing Projects, Namespaces and Workloads]({{}}/rancher/v2.5/en/cluster-admin/projects-and-namespaces/) | ✓ | ✓ | ✓ | -| [Using App Catalogs]({{}}/rancher/v2.5/en/catalog/) | ✓ | ✓ | ✓ | -| [Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)]({{}}/rancher/v2.5/en/cluster-admin/tools/) | ✓ | ✓ | ✓ | -| [Running Security Scans]({{}}/rancher/v2.5/en/security/security-scan/) | ✓ | ✓ | ✓ | -| [Cloning Clusters]({{}}/rancher/v2.5/en/cluster-admin/cloning-clusters/)| ✓ | ✓ | | -| [Ability to rotate certificates]({{}}/rancher/v2.5/en/cluster-admin/certificate-rotation/) | ✓ | | | -| [Ability to back up your Kubernetes Clusters]({{}}/rancher/v2.5/en/cluster-admin/backing-up-etcd/) | ✓ | | | -| [Ability to recover and restore etcd]({{}}/rancher/v2.5/en/cluster-admin/restoring-etcd/) | ✓ | | | -| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{}}/rancher/v2.5/en/cluster-admin/cleaning-cluster-nodes/) | ✓ | | | -| [Configuring Pod Security Policies]({{}}/rancher/v2.5/en/cluster-admin/pod-security-policy/) | ✓ | | | + +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} + +| Action | Rancher Launched Kubernetes Clusters | EKS and GKE Clusters* | Other Hosted Kubernetes Clusters | Non-EKS or GKE Registered Clusters | +| --- | --- | ---| ---|----| +| [Using kubectl and a kubeconfig file to Access a Cluster]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/kubectl/) | ✓ | ✓ | ✓ | ✓ | +| [Managing Cluster Members]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/cluster-members/) | ✓ | ✓ | ✓ | ✓ | +| [Editing and Upgrading Clusters]({{}}/rancher/v2.5/en/cluster-admin/editing-clusters/) | ✓ | ✓ | ✓ | ** | +| [Managing Nodes]({{}}/rancher/v2.5/en/cluster-admin/nodes) | ✓ | ✓ | ✓ | ✓ *** | +| [Managing Persistent Volumes and Storage Classes]({{}}/rancher/v2.5/en/cluster-admin/volumes-and-storage/) | ✓ | ✓ | ✓ | ✓ | +| [Managing Projects, Namespaces and Workloads]({{}}/rancher/v2.5/en/cluster-admin/projects-and-namespaces/) | ✓ | ✓ | ✓ | ✓ | +| [Using App Catalogs]({{}}/rancher/v2.5/en/catalog/) | ✓ | ✓ | ✓ | ✓ | +| [Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)]({{}}/rancher/v2.5/en/cluster-admin/tools/) | ✓ | ✓ | ✓ | ✓ | +| [Running Security Scans]({{}}/rancher/v2.5/en/security/security-scan/) | ✓ | ✓ | ✓ | ✓ | +| [Cloning Clusters]({{}}/rancher/v2.5/en/cluster-admin/cloning-clusters/)| ✓ | ✓ |✓ | | +| [Ability to rotate certificates]({{}}/rancher/v2.5/en/cluster-admin/certificate-rotation/) | ✓ | ✓ | | | +| [Ability to back up your Kubernetes Clusters]({{}}/rancher/v2.5/en/cluster-admin/backing-up-etcd/) | ✓ | ✓ | | | +| [Ability to recover and restore etcd]({{}}/rancher/v2.5/en/cluster-admin/restoring-etcd/) | ✓ | ✓ | | | +| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{}}/rancher/v2.5/en/cluster-admin/cleaning-cluster-nodes/) | ✓ | | | | +| [Configuring Pod Security Policies]({{}}/rancher/v2.5/en/cluster-admin/pod-security-policy/) | ✓ | ✓ | || + +\* Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, [it is not destroyed.]({{}}/rancher/v2.5/en/cluster-provisioning/registered-clusters/#additional-features-for-registered-eks-and-gke-clusters) + +\* \* Cluster configuration options can't be edited for imported clusters, except for [K3s and RKE2 clusters.]({{}}/rancher/v2.5/en/cluster-provisioning/imported-clusters/) + +\* \* \* For registered cluster nodes, the Rancher UI exposes the ability to cordon drain, and edit the node. + +{{% /tab %}} +{{% tab "Rancher v2.5.0-v2.5.7" %}} + +| Action | Rancher Launched Kubernetes Clusters | Hosted Kubernetes Clusters | Registered EKS Clusters | All Other Registered Clusters | +| --- | --- | ---| ---|----| +| [Using kubectl and a kubeconfig file to Access a Cluster]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/kubectl/) | ✓ | ✓ | ✓ | ✓ | +| [Managing Cluster Members]({{}}/rancher/v2.5/en/cluster-admin/cluster-access/cluster-members/) | ✓ | ✓ | ✓ | ✓ | +| [Editing and Upgrading Clusters]({{}}/rancher/v2.5/en/cluster-admin/editing-clusters/) | ✓ | ✓ | ✓ | * | +| [Managing Nodes]({{}}/rancher/v2.5/en/cluster-admin/nodes) | ✓ | ✓ | ✓ | ✓ ** | +| [Managing Persistent Volumes and Storage Classes]({{}}/rancher/v2.5/en/cluster-admin/volumes-and-storage/) | ✓ | ✓ | ✓ | ✓ | +| [Managing Projects, Namespaces and Workloads]({{}}/rancher/v2.5/en/cluster-admin/projects-and-namespaces/) | ✓ | ✓ | ✓ | ✓ | +| [Using App Catalogs]({{}}/rancher/v2.5/en/catalog/) | ✓ | ✓ | ✓ | ✓ | +| [Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)]({{}}/rancher/v2.5/en/cluster-admin/tools/) | ✓ | ✓ | ✓ | ✓ | +| [Running Security Scans]({{}}/rancher/v2.5/en/security/security-scan/) | ✓ | ✓ | ✓ | ✓ | +| [Cloning Clusters]({{}}/rancher/v2.5/en/cluster-admin/cloning-clusters/)| ✓ | ✓ |✓ | | +| [Ability to rotate certificates]({{}}/rancher/v2.5/en/cluster-admin/certificate-rotation/) | ✓ | | ✓ | | +| [Ability to back up your Kubernetes Clusters]({{}}/rancher/v2.5/en/cluster-admin/backing-up-etcd/) | ✓ | | ✓ | | +| [Ability to recover and restore etcd]({{}}/rancher/v2.5/en/cluster-admin/restoring-etcd/) | ✓ | | ✓ | | +| [Cleaning Kubernetes components when clusters are no longer reachable from Rancher]({{}}/rancher/v2.5/en/cluster-admin/cleaning-cluster-nodes/) | ✓ | | | | +| [Configuring Pod Security Policies]({{}}/rancher/v2.5/en/cluster-admin/pod-security-policy/) | ✓ | | ✓ || \* Cluster configuration options can't be edited for imported clusters, except for [K3s and RKE2 clusters.]({{}}/rancher/v2.5/en/cluster-provisioning/imported-clusters/) + +\* \* For registered cluster nodes, the Rancher UI exposes the ability to cordon drain, and edit the node. + + +{{% /tab %}} +{{% /tabs %}} \ No newline at end of file diff --git a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md index 92fab1a1bce..437daf93b53 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/eks/_index.md @@ -712,30 +712,31 @@ Permissions required for Rancher to create VPC and associated resources. } ``` - # Syncing -Syncing is the feature that causes Rancher to update its EKS clusters' values so they are up to date with their corresponding cluster object in the EKS console. This enables Rancher to not be the sole owner of an EKS cluster’s state. Its largest limitation is that processing an update from Rancher and another source at the same time or within 5 minutes of one finishing may cause the state from one source to completely overwrite the other. - -### How it works - -There are two fields on the Rancher Cluster object that must be understood to understand how syncing works: - -1. EKSConfig which is located on the Spec of the Cluster. -2. UpstreamSpec which is located on the EKSStatus field on the Status of the Cluster. - -Both of which are defined by the struct EKSClusterConfigSpec found in the eks-operator project: https://github.com/rancher/eks-operator/blob/master/pkg/apis/eks.cattle.io/v1/types.go - -All fields with the exception of DisplayName, AmazonCredentialSecret, Region, and Imported are nillable on the EKSClusterConfigSpec. - -The EKSConfig represents desired state for its non-nil values. Fields that are non-nil in the EKSConfig can be thought of as “managed".When a cluster is created in Rancher, all fields are non-nil and therefore “managed”. When a pre-existing cluster is registered in rancher all nillable fields are nil and are not “managed”. Those fields become managed once their value has been changed by Rancher. - -UpstreamSpec represents the cluster as it is in EKS and is refreshed on an interval of 5 minutes. After the UpstreamSpec has been refreshed rancher checks if the EKS cluster has an update in progress. If it is updating, nothing further is done. If it is not currently updating, any “managed” fields on EKSConfig are overwritten with their corresponding value from the recently updated UpstreamSpec. - -The effective desired state can be thought of as the UpstreamSpec + all non-nil fields in the EKSConfig. This is what is displayed in the UI. - -If Rancher and another source attempt to update an EKS cluster at the same time or within the 5 minute refresh window of an update finishing, then it is likely any “managed” fields can be caught in a race condition. For example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console, then finishes at 11:01, and then tags are updated from Rancher before 11:05 the value will likely be overwritten. This would also occur if tags were updated while the cluster was processing the update. If the cluster was registered and the PrivateAccess fields was nil then this issue should not occur in the aforementioned case. +The EKS provisioner can synchronize the state of an EKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see [Syncing.](../syncing) ### Configuring the Refresh Interval -It is possible to change the refresh interval through the setting “eks-refresh-cron". This setting accepts values in the Cron format. The default is `*/5 * * * *`. The shorter the refresh window is the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs. +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +The `eks-refresh-cron` setting is deprecated. It has been migrated to the `eks-refresh` setting, which is an integer representing seconds. + +The default value is 300 seconds. + +The syncing interval can be changed by running `kubectl edit setting eks-refresh`. + +If the `eks-refresh-cron` setting was previously set, the migration will happen automatically. + +The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs. + +{{% /tab %}} +{{% tab "Before v2.5.8" %}} + +It is possible to change the refresh interval through the setting `eks-refresh-cron`. This setting accepts values in the Cron format. The default is `*/5 * * * *`. + +The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs. + +{{% /tab %}} +{{% /tabs %}} diff --git a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md index 04e27648067..a2541bd4a10 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/_index.md @@ -1,15 +1,26 @@ --- -title: Creating a GKE Cluster +title: Managing GKE Clusters shortTitle: Google Kubernetes Engine weight: 2105 aliases: - /rancher/v2.5/en/tasks/clusters/creating-a-cluster/create-cluster-gke/ --- -## Prerequisites in Google Kubernetes Engine +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} ->**Note** ->Deploying to GKE will incur charges. +- [Prerequisites](#prerequisites) +- [Provisioning a GKE Cluster](#provisioning-a-gke-cluster) +- [Private Clusters](#private-clusters) +- [Configuration Reference](./config-reference) +- [Updating Kubernetes Version](#updating-kubernetes-version) +- [Syncing](#syncing) + +# Prerequisites + +Some setup in Google Kubernetes Engine is required. + +### Service Account Token Create a service account using [Google Kubernetes Engine](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts). GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication. @@ -22,7 +33,108 @@ The service account requires the following roles: [Google Documentation: Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) -## Create the GKE Cluster +For help obtaining a private key for your service account, refer to the Google cloud documentation [here.](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) You will need to save the key in JSON format. + +### Google Project ID + +Your cluster will need to be part of a Google Project. + +To create a new project, refer to the Google cloud documentation [here.](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project) + +To get the project ID of an existing project, refer to the Google cloud documentation [here.](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects) + +# Provisioning a GKE Cluster + +>**Note** +>Deploying to GKE will incur charges. + +### 1. Create a Cloud Credential + +1. In the upper right corner, click the user profile dropdown menu and click **Cloud Credentials.** +1. Click **Add Cloud Credential.** +1. Enter a name for your Google cloud credentials. +1. In the **Cloud Credential Type** field, select **Google.** +1. In the **Service Account** text box, paste your service account private key JSON, or upload the JSON file. +1. Click **Create.** + +**Result:** You have created credentials that Rancher will use to provision the new GKE cluster. + +### 2. Create the GKE Cluster +Use Rancher to set up and configure your Kubernetes cluster. + +1. From the **Clusters** page, click **Add Cluster**. +1. Under **With a hosted Kubernetes provider,** click **Google GKE**. +1. Enter a **Cluster Name**. +1. Optional: 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. Optional: Add Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to the cluster. +1. Enter your Google project ID and your Google cloud credentials. +1. Fill out the rest of the form. For help, refer to the [GKE cluster configuration reference.](./config-reference) +1. Click **Create.** + +**Result:** You have successfully deployed a GKE cluster. + +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: + +- `Default`, containing the `default` namespace +- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +# Private Clusters + +Private GKE clusters are supported. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see [this section.](./private-clusters) + +# Configuration Reference + +More configuration options are available for v2.5.8. For details on configuring GKE clusters in Rancher, see [this page.](./config-reference) +# Updating Kubernetes Version + +The Kubernetes version of a cluster can be upgraded to any version available in the region or zone fo the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently. + +>**Note** +>GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the [Google documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#disabling_authentication_with_a_static_password). After this, the Kubernetes version can be updated to 1.19+ via Rancher. + +# Syncing + +The GKE provisioner can synchronize the state of an GKE cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see [Syncing.](../syncing) + +### Configuring the Refresh Interval + +The refresh interval can be configured through the setting "gke-refresh", which is an integer representing seconds. + +The default value is 300 seconds. + +The syncing interval can be changed by running `kubectl edit setting gke-refresh`. + +The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for GCP APIs. + +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + +# Prerequisites + +Some setup in Google Kubernetes Engine is required. + +### Service Account Token + +Create a service account using [Google Kubernetes Engine](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts). GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication. + +The service account requires the following roles: + +- **Compute Viewer:** `roles/compute.viewer` +- **Project Viewer:** `roles/viewer` +- **Kubernetes Engine Admin:** `roles/container.admin` +- **Service Account User:** `roles/iam.serviceAccountUser` + +[Google Documentation: Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + + +>**Note** +>Deploying to GKE will incur charges. + +# Create the GKE Cluster Use Rancher to set up and configure your Kubernetes cluster. @@ -38,13 +150,10 @@ Use Rancher to set up and configure your Kubernetes cluster. >**Note:** After submitting your private key, you may have to enable the Google Kubernetes Engine API. If prompted, browse to the URL displayed in the Rancher UI to enable the API. -6. Select your **Cluster Options** -7. Customize your **Node Options** - * Enabling the Auto Upgrade feature for Nodes is not recommended. -8. Select your **Security Options** +6. Select your cluster options, node options and security options. For help, refer to the [GKE Cluster Configuration Reference.](#gke-before-v2-5-8) 9. Review your options to confirm they're correct. Then click **Create**. -**Result:** +**Result:** You have successfully deployed a GKE cluster. Your cluster is created and assigned a state of **Provisioning.** Rancher is standing up your cluster. @@ -54,3 +163,6 @@ You can access your cluster after its state is updated to **Active.** - `Default`, containing the `default` namespace - `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces + +{{% /tab %}} +{{% /tabs %}} diff --git a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/config-reference/_index.md b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/config-reference/_index.md new file mode 100644 index 00000000000..c64ef97cbf6 --- /dev/null +++ b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/config-reference/_index.md @@ -0,0 +1,360 @@ +--- +title: GKE Cluster Configuration Reference +weight: 1 +--- + +{{% tabs %}} +{{% tab "v2.5.8" %}} + +### Changes in v2.5.8 + +- We now support private GKE clusters. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see [this section.]({{}}/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/#private-clusters) +- [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc) are now supported. +- We now support more configuration options for Rancher managed GKE clusters: + - Project + - Network policy + - Network policy config + - Node pools and node configuration options: + - More image types are available for the nodes + - The maximum number of pods per node can be configured + - Node pools can be added while configuring the GKE cluster +- When provisioning a GKE cluster, you can now use reusable cloud credentials instead of using a service account token directly to create the cluster. + +# Cluster Location + +| Value | Description | +|--------|--------------| +| Location Type | Zonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to [these docs.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane) | +| Zone | Each region in Compute engine contains a number of zones. For more information about available regions and zones, refer to [these docs.](https://cloud.google.com/compute/docs/regions-zones#available) | +| Additional Zones | For zonal clusters, you can select additional zones to create a [multi-zone cluster.](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters) | +| Region | For [regional clusters,](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters) you can select a region. For more information about available regions and zones, refer to [this section](https://cloud.google.com/compute/docs/regions-zones#available). The first part of each zone name is the name of the region. | + +# Cluster Options + +### Kubernetes Version + +For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning) + +### Container Address Range + +The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster. + +### Network + +The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to [this page](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets). + +### Node Subnet / Subnet + +The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the **Network** field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, **Subnetwork Name** is required to generate one. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets) + +### Subnetwork Name + +Automatically create a subnetwork with the provided name. Required if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. For more information on subnetworks, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets) + +### Ip Aliases + +Enable [alias IPs](https://cloud.google.com/vpc/docs/alias-ip). This enables VPC-native traffic routing. Required if using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc). + +### Network Policy + +Enable network policy enforcement on the cluster. A network policy defines the level of communication that can occur between pods and services in the cluster. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/network-policy) + +### Node Ipv4 CIDR Block + +The IP address range of the instance IPs in this cluster. Can be set if "Auto Create Subnetwork" is selected for **Node Subnet** or **Subnet**. Must be a valid CIDR range, e.g. 10.96.0.0/14. For more information on how to determine the IP address range, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing) + +### Cluster Secondary Range Name + +The name of an existing secondary range for Pod IP addresses. If selected, **Cluster Pod Address Range** will automatically be populated. Required if using a Shared VPC network. + +### Cluster Pod Address Range + +The IP address range assigned to pods in the cluster. Must be a valid CIDR range, e.g. 10.96.0.0/11. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your pods, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_pods) + +### Services Secondary Range Name + +The name of an existing secondary range for service IP addresses. If selected, **Service Address Range** will be automatically populated. Required if using a Shared VPC network. + +### Service Address Range + +The address range assigned to the services in the cluster. Must be a valid CIDR range, e.g. 10.94.0.0/18. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your services, refer to [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing_secondary_range_svcs) + +### Private Cluster + +> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/private-clusters/). + +Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP. + +### Enable Private Endpoint + +> Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the [private cluster guide]({{< baseurl >}}/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/#private-clusters). + +Locks down external access to the control plane endpoint. Only available if **Private Cluster** is also selected. If selected, and if Rancher does not have direct access to the Virtual Private Cloud network the cluster is running in, Rancher will provide a registration command to run on the cluster to enable Rancher to connect to it. + +### Master IPV4 CIDR Block + +The IP range for the control plane VPC. + +### Master Authorized Network + +Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required. + +# Additional Options + +### Cluster Addons + +Additional Kubernetes cluster components. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters#Cluster.AddonsConfig) + +#### Horizontal Pod Autoscaling + +The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler) + +#### HTTP (L7) Load Balancing + +HTTP (L7) Load Balancing distributes HTTP and HTTPS traffic to backends hosted on GKE. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) + +#### Network Policy Config (master only) + +Configuration for NetworkPolicy. This only tracks whether the addon is enabled or not on the master, it does not track whether network policy is enabled for the nodes. + +### Cluster Features (Alpha Features) + +Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters) + +### Logging Service + +The logging service the cluster uses to write logs. Use either [Cloud Logging](https://cloud.google.com/logging) or no logging service in which case no logs are exported from the cluster. + +### Monitoring Service + +The monitoring service the cluster uses to write metrics. Use either [Cloud Monitoring](https://cloud.google.com/monitoring) or monitoring service in which case no metrics are exported from the cluster. + + +### Maintenance Window + +Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions) + +# Node Pools + +In this section, enter details describing the configuration of each node in the node pool. + +### Kubernetes Version + +The Kubernetes version for each node in the node pool. For more information on GKE Kubernetes versions, refer to [these docs.](https://cloud.google.com/kubernetes-engine/versioning) + +### Image Type + +The node operating system image. For more information for the node image options that GKE offers for each OS, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) + +> Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the [legacy logging]({{}}/rancher/v2.0-v2.4/en/cluster-admin/tools/logging) implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The [logging feature as of v2.5]({{}}/rancher/v2.5/en/logging) is compatible with the Container-Optimized OS image. + +> Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool. + +### Machine Type + +The virtualized hardware resources available to node instances. For more information on Google Cloud machine types, refer to [this page.](https://cloud.google.com/compute/docs/machine-types#machine_types) + +### Root Disk Type + +Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to [this section.](https://cloud.google.com/compute/docs/disks) + +### Local SSD Disks + +Configure each node's local SSD disk storage in GB. Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see [this section.](https://cloud.google.com/compute/docs/disks#localssds) + +### Preemptible nodes (beta) + +Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms) + +### Taints + +When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool. + +### Node Labels + +You can apply labels to the node pool, which applies the labels to all nodes in the pool. + + +# Group Details + +In this section, enter details describing the node pool. + +### Name + +Enter a name for the node pool. + +### Initial Node Count + +Integer for the starting number of nodes in the node pool. + +### Max Pod Per Node + +GKE has a hard limit of 110 Pods per node. For more information on the Kubernetes limits, see [this section.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#dimension_limits) + +### Autoscaling + +Node pool autoscaling dynamically creates or deletes nodes based on the demands of your workload. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/cluster-autoscaler) + +### Auto Repair + +GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on [auto-repairing nodes.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair) + +### Auto Upgrade + +When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is [updated on your behalf.](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades) For more information about auto-upgrading nodes, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) + +### Access Scopes + +Access scopes are the legacy method of specifying permissions for your nodes. + +- **Allow default access:** The default access for new clusters is the [Compute Engine default service account.](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account) +- **Allow full access to all Cloud APIs:** Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance. +- **Set access for each API:** Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call. + +For more information, see the [section about enabling service accounts for a VM.](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + + +# Labels & Annotations + +Add Kubernetes [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to the cluster. + +# Kubernetes Options + +### Location Type +Zonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to [these docs.](https://cloud.google.com/kubernetes-engine/docs/best-practices/scalability#choosing_a_regional_or_zonal_control_plane) + +For [regional clusters,](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#regional_clusters) you can select a region. For more information about available regions and zones, refer to [this section](https://cloud.google.com/compute/docs/regions-zones#available). The first part of each zone name is the name of the region. + +The location type can't be changed after the cluster is created. + +### Zone +Each region in Compute engine contains a number of zones. + +For more information about available regions and zones, refer to [these docs.](https://cloud.google.com/compute/docs/regions-zones#available) + +### Additional Zones +For zonal clusters, you can select additional zones to create a [multi-zone cluster.](https://cloud.google.com/kubernetes-engine/docs/concepts/types-of-clusters#multi-zonal_clusters) + +### Kubernetes Version +Link to list of GKE kubernetes versions + +### Container Address Range + +The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster. + +### Alpha Features + +Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to [this page](https://cloud.google.com/kubernetes-engine/docs/concepts/alpha-clusters). + +### Legacy Authorization + +This option is deprecated and it is recommended to leave it disabled. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/hardening-your-cluster#leave_abac_disabled) +### Stackdriver Logging + +Enable logging with Google Cloud's Operations Suite, formerly called Stackdriver. For details, see the [documentation.](https://cloud.google.com/logging/docs/basic-concepts) +### Stackdriver Monitoring + +Enable monitoring with Google Cloud's Operations Suite, formerly called Stackdriver. For details, see the [documentation.](https://cloud.google.com/monitoring/docs/monitoring-overview) +### Kubernetes Dashboard + +Enable the [Kubernetes dashboard add-on.](https://cloud.google.com/kubernetes-engine/docs/concepts/dashboards#kubernetes_dashboard) Starting with GKE v1.15, you will no longer be able to enable the Kubernetes Dashboard by using the add-on API. +### Http Load Balancing + +Set up [HTTP(S) load balancing.](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) To use Ingress, you must have the HTTP(S) Load Balancing add-on enabled. +### Horizontal Pod Autoscaling + +The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see the [documentation.](https://cloud.google.com/kubernetes-engine/docs/concepts/horizontalpodautoscaler) +### Maintenance Window + +Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/maintenance-windows-and-exclusions) + +### Network + +The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to [this page](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets). + +### Node Subnet / Subnet + +The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the **Network** field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, **Subnetwork Name** is required to generate one. If using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc), the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to [this page.](https://cloud.google.com/vpc/docs/vpc#vpc_networks_and_subnets) +### Ip Aliases + +Enable [alias IPs](https://cloud.google.com/vpc/docs/alias-ip). This enables VPC-native traffic routing. Required if using [Shared VPCs](https://cloud.google.com/vpc/docs/shared-vpc). + +### Pod address range + +When you create a VPC-native cluster, you specify a subnet in a VPC network. The cluster uses three unique subnet IP address ranges for nodes, pods, and services. For more information on IP address ranges, see [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing) + +### Service address range + +When you create a VPC-native cluster, you specify a subnet in a VPC network. The cluster uses three unique subnet IP address ranges for nodes, pods, and services. For more information on IP address ranges, see [this section.](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips#cluster_sizing) +### Cluster Labels + +A [cluster label](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-managing-labels) is a key-value pair that helps you organize your Google Cloud clusters. You can attach a label to each resource, then filter the resources based on their labels. Information about labels is forwarded to the billing system, so you can break down your billing charges by label. + +## Node Options + +### Node Count +Integer for the starting number of nodes in the node pool. + +### Machine Type +For more information on Google Cloud machine types, refer to [this page.](https://cloud.google.com/compute/docs/machine-types#machine_types) + +### Image Type +Ubuntu or Container-Optimized OS images are available. + +For more information about GKE node image options, refer to [this page.](https://cloud.google.com/kubernetes-engine/docs/concepts/node-images#available_node_images) + +### Root Disk Type + +Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to [this section.](https://cloud.google.com/compute/docs/disks) + +### Root Disk Size +The size in GB of the [root disk.](https://cloud.google.com/compute/docs/disks) + +### Local SSD disks +Configure each node's local SSD disk storage in GB. + +Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see [this section.](https://cloud.google.com/compute/docs/disks#localssds) + +### Preemptible nodes (beta) + +Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/preemptible-vms) + +### Auto Upgrade + +> Note: Enabling the Auto Upgrade feature for Nodes is not recommended. + +When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is [updated on your behalf.](https://cloud.google.com/kubernetes-engine/upgrades#automatic_cp_upgrades) For more information about auto-upgrading nodes, see [this page.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) + +### Auto Repair + +GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on [auto-repairing nodes.](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-repair) + +### Node Pool Autoscaling + +Enable node pool autoscaling based on cluster load. For more information, see the documentation on [adding a node pool with autoscaling.](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-autoscaler#adding_a_node_pool_with_autoscaling) + +### Taints +When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool. +### Node Labels +You can apply labels to the node pool, which applies the labels to all nodes in the pool. + +## Security Options + +### Service Account + +Create a [Service Account](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts) with a JSON private key and provide the JSON here. See [Google Cloud docs](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) for more info about creating a service account. These IAM roles are required: Compute Viewer (`roles/compute.viewer`), (Project) Viewer (`roles/viewer`), Kubernetes Engine Admin (`roles/container.admin`), Service Account User (`roles/iam.serviceAccountUser`). More info on roles can be found [here.](https://cloud.google.com/kubernetes-engine/docs/how-to/iam-integration) + +### Access Scopes + +Access scopes are the legacy method of specifying permissions for your nodes. + +- **Allow default access:** The default access for new clusters is the [Compute Engine default service account.](https://cloud.google.com/compute/docs/access/service-accounts?hl=en_US#default_service_account) +- **Allow full access to all Cloud APIs:** Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance. +- **Set access for each API:** Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call. + +For more information, see the [section about enabling service accounts for a VM.](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) +{{% /tab %}} +{{% /tabs %}} diff --git a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/private-clusters/_index.md b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/private-clusters/_index.md new file mode 100644 index 00000000000..d938b790361 --- /dev/null +++ b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/gke/private-clusters/_index.md @@ -0,0 +1,42 @@ + +title: Private Clusters +weight: 2 +--- + +In GKE, [private clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/private-cluster-concept) are clusters whose nodes are isolated from inbound and outbound traffic by assigning them internal IP addresses only. Private clusters in GKE have the option of exposing the control plane endpoint as a publicly accessible address or as a private address. This is different from other Kubernetes providers, which may refer to clusters with private control plane endpoints as "private clusters" but still allow traffic to and from nodes. You may want to create a cluster with private nodes, with or without a public control plane endpoint, depending on your organization's networking and security requirements. A GKE cluster provisioned from Rancher can use isolated nodes by selecting "Private Cluster" in the Cluster Options (under "Show advanced options"). The control plane endpoint can optionally be made private by selecting "Enable Private Endpoint". + +### Private Nodes + +Because the nodes in a private cluster only have internal IP addresses, they will not be able to install the cluster agent and Rancher will not be able to fully manage the cluster. This can be overcome in a few ways. + +#### Cloud NAT + +>**Note** +>Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +If restricting outgoing internet access is not a concern for your organization, use Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service to allow nodes in the private network to access the internet, enabling them to download the required images from Dockerhub and contact the Rancher management server. This is the simplest solution. + +#### Private registry + +>**Note** +>This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient. + +If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image [registry](https://rancher.com/docs/rancher/v2.x/en/installation/other-installation-methods/air-gap/) on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need [direct access](#direct-access) to it. + +### Private Control Plane Endpoint + +If the cluster has a public endpoint exposed, Rancher will be able to reach the cluster, and no additional steps need to be taken. However, if the cluster has no public endpoint, then considerations must be made to ensure Rancher can access the cluster. + +#### Cloud NAT + +>**Note** +>Cloud NAT will [incur charges](https://cloud.google.com/nat/pricing). + +As above, if restricting outgoing internet access to the nodes is not a concern, then Google's [Cloud NAT](https://cloud.google.com/nat/docs/using-nat) service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the [kubeconfig](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for the new cluster and run the provided kubectl command on the cluster. Gaining access +to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes. + +#### Direct access + +If the Rancher server is run on the same VPC as the cluster's control plane, it will have direct access to the control plane's private endpoint. The cluster nodes will need to have access to a [private registry](#private-registry) to download images as described above. + +You can also use services from Google such as [Cloud VPN](https://cloud.google.com/network-connectivity/docs/vpn/concepts/overview) or [Cloud Interconnect VLAN](https://cloud.google.com/network-connectivity/docs/interconnect) to facilitate connectivity between your organization's network and your Google VPC. diff --git a/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/syncing/_index.md b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/syncing/_index.md new file mode 100644 index 00000000000..03184492969 --- /dev/null +++ b/content/rancher/v2.5/en/cluster-provisioning/hosted-kubernetes-clusters/syncing/_index.md @@ -0,0 +1,32 @@ +# Syncing + +Syncing is the feature for EKS and GKE clusters that causes Rancher to update the clusters' values so they are up to date with their corresponding cluster object in the hosted Kubernetes provider. This enables Rancher to not be the sole owner of a hosted cluster’s state. Its largest limitation is that processing an update from Rancher and another source at the same time or within 5 minutes of one finishing may cause the state from one source to completely overwrite the other. + +### How it works + +There are two fields on the Rancher Cluster object that must be understood to understand how syncing works: + +1. The config object for the cluster, located on the Spec of the Cluster: + + * For EKS, the field is called EKSConfig + * For GKE, the field is called GKEConfig + +2. The UpstreamSpec object + + * For EKS, this is located on the EKSStatus field on the Status of the Cluster. + * For GKE, this is located on the GKEStatus field on the Status of the Cluster. + +The struct types that define these objects can be found in their corresponding operator projects: + + * [eks-operator](https://github.com/rancher/eks-operator/blob/master/pkg/apis/eks.cattle.io/v1/types.go) + * [gke-operator](https://github.com/rancher/gke-operator/blob/master/pkg/apis/gke.cattle.io/v1/types.go) + +All fields with the exception of the cluster name, the location (region or zone), Imported, and the cloud credential reference, are nillable on this Spec object. + +The EKSConfig or GKEConfig represents desired state for its non-nil values. Fields that are non-nil in the config object can be thought of as “managed". When a cluster is created in Rancher, all fields are non-nil and therefore “managed”. When a pre-existing cluster is registered in rancher all nillable fields are nil and are not “managed”. Those fields become managed once their value has been changed by Rancher. + +UpstreamSpec represents the cluster as it is in the hosted Kubernetes provider and is refreshed on an interval of 5 minutes. After the UpstreamSpec has been refreshed, Rancher checks if the cluster has an update in progress. If it is updating, nothing further is done. If it is not currently updating, any “managed” fields on EKSConfig or GKEConfig are overwritten with their corresponding value from the recently updated UpstreamSpec. + +The effective desired state can be thought of as the UpstreamSpec + all non-nil fields in the EKSConfig or GKEConfig. This is what is displayed in the UI. + +If Rancher and another source attempt to update a cluster at the same time or within the 5 minute refresh window of an update finishing, then it is likely any “managed” fields can be caught in a race condition. To use EKS as an example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console, then finishes at 11:01, and then tags are updated from Rancher before 11:05 the value will likely be overwritten. This would also occur if tags were updated while the cluster was processing the update. If the cluster was registered and the PrivateAccess fields was nil then this issue should not occur in the aforementioned case. diff --git a/content/rancher/v2.5/en/cluster-provisioning/registered-clusters/_index.md b/content/rancher/v2.5/en/cluster-provisioning/registered-clusters/_index.md index 5d8553db48e..f8e7a29a2a8 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/registered-clusters/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/registered-clusters/_index.md @@ -5,20 +5,13 @@ aliases: - /rancher/v2.5/en/cluster-provisioning/imported-clusters --- -_Available as of v2.5_ - The cluster registration feature replaced the feature to import clusters. The control that Rancher has to manage a registered cluster depends on the type of cluster. For details, see [Management Capabilities for Registered Clusters.](#management-capabilities-for-registered-clusters) -Registering EKS clusters now provides additional benefits. - - [Prerequisites](#prerequisites) - [Registering a Cluster](#registering-a-cluster) - [Management Capabilities for Registered Clusters](#management-capabilities-for-registered-clusters) - - [Features for All Registered Clusters](#features-for-all-registered-clusters) - - [Additional Features for Registered K3s Clusters](#additional-features-for-registered-k3s-clusters) - - [Additional Features for Registered EKS Clusters](#additional-features-for-registered-eks-clusters) - [Configuring K3s Cluster Upgrades](#configuring-k3s-cluster-upgrades) - [Debug Logging and Troubleshooting for Registered K3s Clusters](#debug-logging-and-troubleshooting-for-registered-k3s-clusters) - [Annotating Registered Clusters](#annotating-registered-clusters) @@ -85,6 +78,19 @@ $ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s - The control that Rancher has to manage a registered cluster depends on the type of cluster. +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +- [Changes in v2.5.8](#changes-in-v2-5-8) +- [Features for All Registered Clusters](#2-5-8-features-for-all-registered-clusters) +- [Additional Features for Registered K3s Clusters](#2-5-8-additional-features-for-registered-k3s-clusters) +- [Additional Features for Registered EKS and GKE Clusters](#additional-features-for-registered-eks-and-gke-clusters) + +### Changes in v2.5.8 + +Greater management capabilities are now available for [registered GKE clusters.](#additional-features-for-registered-eks-and-gke-clusters) The same configuration options are available for registered GKE clusters as for the GKE clusters created through the Rancher UI. + + ### Features for All Registered Clusters After registering a cluster, the cluster owner can: @@ -96,6 +102,48 @@ After registering a cluster, the cluster owner can: - Use [pipelines]({{}}/rancher/v2.5/en/project-admin/pipelines/) - Manage projects and workloads + +### Additional Features for Registered K3s Clusters + +[K3s]({{}}/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution. + +When a K3s cluster is registered in Rancher, Rancher will recognize it as K3s. The Rancher UI will expose the features for [all registered clusters,](#features-for-all-registered-clusters) in addition to the following features for editing and upgrading the cluster: + +- The ability to [upgrade the K3s version]({{}}/rancher/v2.5/en/cluster-admin/upgrading-kubernetes/) +- The ability to configure the maximum number of nodes that will be upgraded concurrently +- The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster + +### Additional Features for Registered EKS and GKE Clusters + +Registering an Amazon EKS cluster or GKE cluster allows Rancher to treat it as though it were created in Rancher. + +Amazon EKS clusters and GKE clusters can now be registered in Rancher. For the most part, these registered clusters are treated the same way as clusters created in the Rancher UI, except for deletion. + +When you delete an EKS cluster or GKE cluster that was created in Rancher, the cluster is destroyed. When you delete a cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher. + +The capabilities for registered clusters are listed in the table on [this page.]({{}}/rancher/v2.5/en/cluster-provisioning/) + + +{{% /tab %}} +{{% tab "Rancher v2.5.0-v2.5.8" %}} + +- [Features for All Registered Clusters](#before-2-5-8-features-for-all-registered-clusters) +- [Additional Features for Registered K3s Clusters](#before-2-5-8-additional-features-for-registered-k3s-clusters) +- [Additional Features for Registered EKS Clusters](#additional-features-for-registered-eks-clusters) + + +### Features for All Registered Clusters + +After registering a cluster, the cluster owner can: + +- [Manage cluster access]({{}}/rancher/v2.5/en/admin-settings/rbac/cluster-project-roles/) through role-based access control +- Enable [monitoring, alerts and notifiers]({{}}/rancher/v2.5/en/monitoring-alerting/v2.5/) +- Enable [logging]({{}}/rancher/v2.5/en/logging/v2.5/) +- Enable [Istio]({{}}/rancher/v2.5/en/istio/v2.5/) +- Use [pipelines]({{}}/rancher/v2.5/en/project-admin/pipelines/) +- Manage projects and workloads + + ### Additional Features for Registered K3s Clusters [K3s]({{}}/k3s/latest/en/) is a lightweight, fully compliant Kubernetes distribution. @@ -115,6 +163,10 @@ Amazon EKS clusters can now be registered in Rancher. For the most part, registe When you delete an EKS cluster that was created in Rancher, the cluster is destroyed. When you delete an EKS cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher. The capabilities for registered EKS clusters are listed in the table on [this page.]({{}}/rancher/v2.5/en/cluster-provisioning/) +{{% /tab %}} +{{% /tabs %}} + + # Configuring K3s Cluster Upgrades diff --git a/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/_index.md b/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/_index.md index 0e394858eb4..aef26507b12 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/_index.md @@ -19,6 +19,7 @@ This section is a cluster configuration reference, covering the following topics - [Rancher UI Options](#rancher-ui-options) - [Kubernetes version](#kubernetes-version) - [Network provider](#network-provider) + - [Project network isolation](#project-network-isolation) - [Kubernetes cloud providers](#kubernetes-cloud-providers) - [Private registries](#private-registries) - [Authorized cluster endpoint](#authorized-cluster-endpoint) @@ -58,15 +59,28 @@ Out of the box, Rancher is compatible with the following network providers: - [Calico](https://docs.projectcalico.org/v3.11/introduction/) - [Weave](https://github.com/weaveworks/weave) -**Notes on Canal:** - -If you use Canal, you also have the option of using **Project Network Isolation**, which will enable or disable communication between pods in different [projects]({{}}/rancher/v2.5/en/k8s-in-rancher/projects-and-namespaces/). - **Notes on Weave:** When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a [Config File]({{}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/#cluster-config-file) and the [Weave Network Plug-in Options]({{}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options). +### Project Network Isolation + +Project network isolation is used to enable or disable communication between pods in different projects. + +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +To enable project network isolation as a cluster option, you will need to use any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin. + +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + +To enable project network isolation as a cluster option, you will need to use Canal as the CNI. + +{{% /tab %}} +{{% /tabs %}} + ### Kubernetes Cloud Providers You can configure a [Kubernetes cloud provider]({{}}/rancher/v2.5/en/cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage]({{}}/rancher/v2.5/en/k8s-in-rancher/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. @@ -278,6 +292,10 @@ Option to enable or disable [Cluster Monitoring]({{}}/rancher/v2.5/en/m Option to enable or disable Project Network Isolation. +Before Rancher v2.5.8, project network isolation is only available if you are using the Canal network plugin for RKE. + +In v2.5.8+, project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin. + ### local_cluster_auth_endpoint See [Authorized Cluster Endpoint](#authorized-cluster-endpoint). diff --git a/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md b/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md index c69d4dc5445..d4cab37b33d 100644 --- a/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md +++ b/content/rancher/v2.5/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md @@ -33,6 +33,14 @@ The general node requirements for networking, operating systems, and Docker are ### OS and Docker Requirements +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +Our support for Windows Server and Windows containers match the Microsoft official lifecycle for LTSC (Long-Term Servicing Channel) and SAC (Semi-Annual Channel). + +For the support lifecycle dates for Windows Server, see the [Microsoft Documentation.](https://docs.microsoft.com/en-us/windows-server/get-started/windows-server-release-info) +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} In order to add Windows worker nodes to a cluster, the node must be running one of the following Windows Server versions and the corresponding version of Docker Engine - Enterprise Edition (EE): - Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09 or Docker EE-basic 19.03. @@ -42,6 +50,8 @@ In order to add Windows worker nodes to a cluster, the node must be running one > > - If you are using AWS, Rancher recommends _Microsoft Windows Server 2019 Base with Containers_ as the Amazon Machine Image (AMI). > - If you are using GCE, Rancher recommends _Windows Server 2019 Datacenter for Containers_ as the OS image. +{{% /tab %}} +{{% /tabs %}} ### Kubernetes Version diff --git a/content/rancher/v2.5/en/faq/removing-rancher/_index.md b/content/rancher/v2.5/en/faq/removing-rancher/_index.md index 5b18507f4dc..be8e6175ddb 100644 --- a/content/rancher/v2.5/en/faq/removing-rancher/_index.md +++ b/content/rancher/v2.5/en/faq/removing-rancher/_index.md @@ -32,6 +32,15 @@ The capability to access a downstream cluster without Rancher depends on the typ If you [installed Rancher on a Kubernetes cluster,]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/) remove Rancher by using the [System Tools]({{}}/rancher/v2.5/en/system-tools/) with the `remove` subcommand. +As of Rancher v2.5.8, uninstalling Rancher in high-availability (HA) mode will also remove all `helm-operation-*` pods and the following apps: + +- fleet +- fleet-agent +- rancher-operator +- rancher-webhook + +Custom resources (CRDs) and custom namespaces will still need to be manually removed. + If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in. Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on [accessing downstream clusters when Rancher is removed.](#if-the-rancher-server-is-deleted-how-do-i-access-my-downstream-clusters) diff --git a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/_index.md b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/_index.md index 5cecd22fac8..7d4887312eb 100644 --- a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/_index.md +++ b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/_index.md @@ -32,7 +32,8 @@ For help setting up a Kubernetes cluster, we provide these tutorials: - **RKE:** For the tutorial to install an RKE Kubernetes cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/ha-rke/) For help setting up the infrastructure for a high-availability RKE cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha) - **K3s:** For the tutorial to install a K3s Kubernetes cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/ha-with-external-db) For help setting up the infrastructure for a high-availability K3s cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-ha-with-external-db) - **RKE2:** For the tutorial to install an RKE2 Kubernetes cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/ha-rke2) For help setting up the infrastructure for a high-availability RKE2 cluster, refer to [this page.]({{}}/rancher/v2.5/en/installation/resources/k8s-tutorials/infrastructure-tutorials/infra-for-rke2-ha) -- **Amazon EKS:** To install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/amazon-eks) +- **Amazon EKS:** For details on how to install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/amazon-eks) +- **GKE:** For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to [this page.]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/gke) ### CLI Tools diff --git a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/gke/_index.md b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/gke/_index.md new file mode 100644 index 00000000000..492a2f60ccc --- /dev/null +++ b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/gke/_index.md @@ -0,0 +1,180 @@ +--- +title: Installing Rancher on a Google Kubernetes Engine Cluster +shortTitle: GKE +weight: 5 +--- + +In this section, you'll learn how to install Rancher using Google Kubernetes Engine. + +If you already have a GKE Kubernetes cluster, skip to the step about [installing an ingress.](#7-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart) + +# Prerequisites + +- You will need a Google account. +- You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit [General guide to the console.](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599) +- You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to [this section.]({{}}/rancher/v2.5/en/installation/requirements/#rke-and-hosted-kubernetes) + +# 1. Enable the Kubernetes Engine API + +Take the following steps to enable the Kubernetes Engine API: + +1. Visit the [Kubernetes Engine page](https://console.cloud.google.com/projectselector/kubernetes?_ga=2.169595943.767329331.1617810440-856599067.1617343886) in the Google Cloud Console. +1. Create or select a project. +1. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes. +1. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the [Google Cloud documentation.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project) + +# 2. Open the Cloud Shell + +Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the `gcloud` command-line tool and kubectl command-line tool. The `gcloud` tool provides the primary command-line interface for Google Cloud, and `kubectl` provides the primary command-line interface for running commands against Kubernetes clusters. + +The following sections describe how to launch the cloud shell from the Google Cloud Console or from your local workstation. + +### Cloud Shell + +To launch the shell from the [Google Cloud Console,](https://console.cloud.google.com) go to the upper-right corner of the console and click the terminal button. When hovering over the button, it is labeled **Activate Cloud Shell.** + +### Local Shell + +To install `gcloud` and `kubectl`, perform the following steps: + +1. Install the Cloud SDK by following [these steps.](https://cloud.google.com/sdk/docs/install) The Cloud SDK includes the `gcloud` command-line tool. The steps vary based on your OS. +1. After installing Cloud SDK, install the `kubectl` command-line tool by running the following command: + + ``` + gcloud components install kubectl + ``` + In a later step, `kubectl` will be configured to use the new GKE cluster. +1. [Install Helm 3](https://helm.sh/docs/intro/install/) if it is not already installed. +1. Enable Helm experimental [support for OCI images](https://github.com/helm/community/blob/master/hips/hip-0006.md) with the `HELM_EXPERIMENTAL_OCI` variable. Add the following line to `~/.bashrc` (or `~/.bash_profile` in macOS, or wherever your shell stores environment variables): + + ``` + export HELM_EXPERIMENTAL_OCI=1 + ``` +1. Run the following command to load your updated `.bashrc` file: + + ``` + source ~/.bashrc + ``` + If you are running macOS, use this command: + ``` + source ~/.bash_profile + ``` + + + +# 3. Configure the gcloud CLI + + Set up default gcloud settings using one of the following methods: + +- Using gcloud init, if you want to be walked through setting defaults. +- Using gcloud config, to individually set your project ID, zone, and region. + +{{% tabs %}} +{{% tab "Using gloud init" %}} + +1. Run gcloud init and follow the directions: + + ``` + gcloud init + ``` + If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser: + + ``` + gcloud init --console-only + ``` +2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created. + +{{% /tab %}} +{{% tab "Using gcloud config" %}} +{{% /tab %}} +{{% /tabs %}} + +# 4. Confirm that gcloud is configured correctly + +Run: + +``` +gcloud config list +``` + +The output should resemble the following: + +``` +[compute] +region = us-west1 # Your chosen region +zone = us-west1-b # Your chosen zone +[core] +account = +disable_usage_reporting = True +project = + +Your active configuration is: [default] +``` + +# 5. Create a GKE Cluster + +The following command creates a three-node cluster. + +Replace `cluster-name` with the name of your new cluster. + +``` +gcloud container clusters create cluster-name --num-nodes=3 +``` + +# 6. Get Authentication Credentials + +After creating your cluster, you need to get authentication credentials to interact with the cluster: + +``` +gcloud container clusters get-credentials cluster-name +``` + +This command configures `kubectl` to use the cluster you created. + +# 7. Install an Ingress + +The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. + +The following command installs an `nginx-ingress-controller` with a LoadBalancer service: + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update +helm upgrade --install \ + ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --set controller.service.type=LoadBalancer \ + --version 3.12.0 \ + --create-namespace +``` + +# 8. Get the Load Balancer IP + +To get the address of the load balancer, run: + +``` +kubectl get service ingress-nginx-controller --namespace=ingress-nginx +``` + +The result should look similar to the following: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +ingress-nginx-controller LoadBalancer 10.3.244.156 35.233.206.34 80:31876/TCP,443:32497/TCP 81s +``` + +Save the `EXTERNAL-IP`. + +# 9. Set up DNS + +External traffic to the Rancher server will need to be directed at the load balancer you created. + +Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL. + +There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about [managing DNS records.](https://cloud.google.com/dns/docs/records) + +# 10. Install the Rancher Helm chart + +Next, install the Rancher Helm chart by following the instructions on [this page.]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution. + +Use the DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`. \ No newline at end of file diff --git a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/_index.md b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/_index.md index 1506c27e27b..f3ac8f7e527 100644 --- a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/_index.md +++ b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/_index.md @@ -53,7 +53,7 @@ For migration of installs started with Helm 2, refer to the official [Helm 2 to ### For air gap installs: Populate private registry --For [air gap installs only,]({{}}/rancher/v2.5/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry]({{}}/rancher/v2.5/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to. +For [air gap installs only,]({{}}/rancher/v2.5/en/installation/other-installation-methods/air-gap) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry]({{}}/rancher/v2.5/en/installation/other-installation-methods/air-gap/populate-private-registry/) with the images for the Rancher version that you want to upgrade to. ### For upgrades from a Rancher server with a hidden local cluster @@ -120,8 +120,8 @@ You'll use the backup as a restoration point if something goes wrong during upgr This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm. -{{% tabs %}} -{{% tab "Kubernetes Upgrade" %}} +> **Air Gap Instructions:** If you are installing Rancher in an air gapped environment, skip the rest of this page and render the Helm template by following the instructions on [this page.](./air-gap-upgrade) + Get the values, which were passed with `--set`, from the current Rancher Helm chart that is installed. @@ -182,74 +182,6 @@ If you are currently running the cert-manger whose version is older than v0.11, --set hostname=rancher.my.org ``` -{{% /tab %}} -{{% tab "Kubernetes Air Gap Upgrade" %}} - -Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. - -Based on the choice you made during installation, complete one of the procedures below. - -Placeholder | Description -------------|------------- -`` | The version number of the output tarball. -`` | The DNS name you pointed at your load balancer. -`` | The DNS name for your private registry. -`` | Cert-manager version running on k8s cluster. - - -### Option A: Default Self-signed Certificate - - ```plain -helm template ./rancher-.tgz --output-dir . \ - --name rancher \ - --namespace cattle-system \ - --set hostname= \ - --set certmanager.version= \ - --set rancherImage=/rancher/rancher \ - --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher - --set useBundledSystemChart=true # Use the packaged Rancher system charts -``` - -### Option B: Certificates from Files using Kubernetes Secrets - -```plain -helm template ./rancher-.tgz --output-dir . \ ---name rancher \ ---namespace cattle-system \ ---set hostname= \ ---set rancherImage=/rancher/rancher \ ---set ingress.tls.source=secret \ ---set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher ---set useBundledSystemChart=true # Use the packaged Rancher system charts -``` - -If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: - -```plain -helm template ./rancher-.tgz --output-dir . \ ---name rancher \ ---namespace cattle-system \ ---set hostname= \ ---set rancherImage=/rancher/rancher \ ---set ingress.tls.source=secret \ ---set privateCA=true \ ---set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher ---set useBundledSystemChart=true # Use the packaged Rancher system charts -``` - -### Apply the Rendered Templates - -Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates. - -Use `kubectl` to apply the rendered manifests. - -```plain -kubectl -n cattle-system apply -R -f ./rancher -``` - -{{% /tab %}} -{{% /tabs %}} - # 4. Verify the Upgrade Log into Rancher to confirm that the upgrade succeeded. diff --git a/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/_index.md b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/_index.md new file mode 100644 index 00000000000..ce0ae4f4838 --- /dev/null +++ b/content/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/air-gap-upgrade/_index.md @@ -0,0 +1,144 @@ +--- +title: Rendering the Helm Template in an Air Gapped Environment +shortTitle: Air Gap Upgrade +weight: 1 +--- + +> These instructions assume you have already followed the instructions for a Kubernetes upgrade on [this page,]({{}}/rancher/v2.5/en/installation/install-rancher-on-k8s/upgrades/) including the prerequisites, up until step 3. Upgrade Rancher. + +### Rancher Helm Template Options + +Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. + +Based on the choice you made during installation, complete one of the procedures below. + +Placeholder | Description +------------|------------- +`` | The version number of the output tarball. +`` | The DNS name you pointed at your load balancer. +`` | The DNS name for your private registry. +`` | Cert-manager version running on k8s cluster. + + +### Option A: Default Self-signed Certificate + +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + + ```plain +helm template ./rancher-.tgz --output-dir . \ + --name rancher \ + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +{{% /tab %}} +{{% /tabs %}} + + + +### Option B: Certificates from Files using Kubernetes Secrets + + +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + + +```plain +helm template ./rancher-.tgz --output-dir . \ + --name rancher \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: + +```plain +helm template ./rancher-.tgz --output-dir . \ + --name rancher \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + + +```plain +helm template ./rancher-.tgz --output-dir . \ +--name rancher \ +--namespace cattle-system \ +--set hostname= \ +--set rancherImage=/rancher/rancher \ +--set ingress.tls.source=secret \ +--set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher +--set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: + +```plain +helm template ./rancher-.tgz --output-dir . \ +--name rancher \ +--namespace cattle-system \ +--set hostname= \ +--set rancherImage=/rancher/rancher \ +--set ingress.tls.source=secret \ +--set privateCA=true \ +--set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher +--set useBundledSystemChart=true # Use the packaged Rancher system charts +``` +{{% /tab %}} +{{% /tabs %}} + + +### Apply the Rendered Templates + +Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates. + +Use `kubectl` to apply the rendered manifests. + +```plain +kubectl -n cattle-system apply -R -f ./rancher +``` + +# Verify the Upgrade + +Log into Rancher to confirm that the upgrade succeeded. + +>**Having network issues following upgrade?** +> +> See [Restoring Cluster Networking]({{}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/upgrades/namespace-migration). + +# Known Upgrade Issues + +A list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12) diff --git a/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/_index.md b/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/_index.md index 7bb8227939f..dda9e56d1ea 100644 --- a/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/_index.md +++ b/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/_index.md @@ -10,18 +10,21 @@ aliases: - /rancher/v2.5/en/installation/air-gap-high-availability/install-rancher/ --- -This section is about how to deploy Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are _tabs_ for either a high availability (recommended) or a Docker installation. +This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. ### Privileged Access for Rancher v2.5+ When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the `--privileged` option. -{{% tabs %}} -{{% tab "Kubernetes Install (Recommended)" %}} +# Docker Instructions + +If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on [this page.](./docker-install-commands) + +# Kubernetes Instructions Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails. -This section describes installing Rancher in five parts: +This section describes installing Rancher: - [1. Add the Helm Chart Repository](#1-add-the-helm-chart-repository) - [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration) @@ -63,7 +66,7 @@ When Rancher is installed on an air gapped Kubernetes cluster, there are two rec | Rancher Generated Self-Signed Certificates | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
This is the **default** and does not need to be added when rendering the Helm template. | yes | | Certificates from Files | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s).
This option must be passed when rendering the Rancher Helm template. | no | -# 3. Render the Rancher Helm Template +# Helm Chart Options for Air Gap Installations When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations. @@ -73,73 +76,108 @@ When setting up the Rancher Helm template, there are several options in the Helm | `systemDefaultRegistry` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | | `useBundledSystemChart` | `true` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | -Based on the choice your made in [B. Choose your SSL Configuration](#b-choose-your-ssl-configuration), complete one of the procedures below. +# 3. Render the Rancher Helm Template -### Option A: Default Self-Signed Certificate +Based on the choice your made in [2. Choose your SSL Configuration](#2-choose-your-ssl-configuration), complete one of the procedures below. + +# Option A: Default Self-Signed Certificate -{{% accordion id="k8s-1" label="Click to expand" %}} By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. > **Note:** > Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our [upgrade cert-manager documentation]({{}}/rancher/v2.5/en/installation/options/upgrading-cert-manager/). -1. From a system connected to the internet, add the cert-manager repo to Helm. - ```plain - helm repo add jetstack https://charts.jetstack.io - helm repo update - ``` +### 1. Add the cert-manager repo -1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). +From a system connected to the internet, add the cert-manager repo to Helm: - ```plain - helm fetch jetstack/cert-manager --version v1.0.4 - ``` +```plain +helm repo add jetstack https://charts.jetstack.io +helm repo update +``` -1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. - ```plain - helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \ - --namespace cert-manager \ - --set image.repository=/quay.io/jetstack/cert-manager-controller \ - --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook \ - --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector - ``` +### 2. Fetch the cert-manager chart -1. Download the required CRD file for cert-manager +Fetch the latest cert-manager chart available from the [Helm chart repository](https://hub.helm.sh/charts/jetstack/cert-manager). + +```plain +helm fetch jetstack/cert-manager --version v1.0.4 +``` + +### 3. Render the cert-manager template + +Render the cert-manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files. + +```plain +helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \ + --namespace cert-manager \ + --set image.repository=/quay.io/jetstack/cert-manager-controller \ + --set webhook.image.repository=/quay.io/jetstack/cert-manager-webhook \ + --set cainjector.image.repository=/quay.io/jetstack/cert-manager-cainjector +``` + +### 4. Download the cert-manager CRD + +Download the required CRD file for cert-manager: ```plain curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml ``` -1. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. +### 5. Render the Rancher template + +Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. - Placeholder | Description - ------------|------------- - `` | The version number of the output tarball. - `` | The DNS name you pointed at your load balancer. - `` | The DNS name for your private registry. - `` | Cert-manager version running on k8s cluster. +Placeholder | Description +------------|------------- +`` | The version number of the output tarball. +`` | The DNS name you pointed at your load balancer. +`` | The DNS name for your private registry. +`` | Cert-manager version running on k8s cluster. - ```plain - helm template rancher ./rancher-.tgz --output-dir . \ - --namespace cattle-system \ - --set hostname= \ - --set certmanager.version= \ - --set rancherImage=/rancher/rancher \ - --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher - --set useBundledSystemChart=true # Use the packaged Rancher system charts +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} +```plain +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts ``` -**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6` +**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.5.8` +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} -{{% /accordion %}} +```plain +helm template rancher ./rancher-.tgz --output-dir . \ + --namespace cattle-system \ + --set hostname= \ + --set certmanager.version= \ + --set rancherImage=/rancher/rancher \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` -### Option B: Certificates From Files using Kubernetes Secrets +**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.5.6` +{{% /tab %}} +{{% /tabs %}} -{{% accordion id="k8s-2" label="Click to expand" %}} + + +# Option B: Certificates From Files using Kubernetes Secrets + + +### 1. Create secrets Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher. +### 2. Render the Rancher template + Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools. | Placeholder | Description | @@ -148,6 +186,41 @@ Render the Rancher template, declaring your chosen options. Use the reference ta | `` | The DNS name you pointed at your load balancer. | | `` | The DNS name for your private registry. | +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +```plain + helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +If you are using a Private CA signed cert, add `--set privateCA=true` following `--set ingress.tls.source=secret`: + +```plain + helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set privateCA=true \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts +``` + +**Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6` + +Then refer to [Adding TLS Secrets]({{}}/rancher/v2.5/en/installation/resources/encryption/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them. +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + + ```plain helm template rancher ./rancher-.tgz --output-dir . \ --namespace cattle-system \ @@ -174,8 +247,10 @@ If you are using a Private CA signed cert, add `--set privateCA=true` following **Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6` Then refer to [Adding TLS Secrets]({{}}/rancher/v2.5/en/installation/resources/encryption/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them. +{{% /tab %}} +{{% /tabs %}} + -{{% /accordion %}} # 4. Install Rancher @@ -228,135 +303,3 @@ These resources could be helpful when installing Rancher: - [Rancher Helm chart options]({{}}/rancher/v2.5/en/installation/resources/chart-options/) - [Adding TLS secrets]({{}}/rancher/v2.5/en/installation/resources/encryption/tls-secrets/) - [Troubleshooting Rancher Kubernetes Installations]({{}}/rancher/v2.5/en/installation/options/troubleshooting/) - -{{% /tab %}} -{{% tab "Docker Install" %}} - -The Docker installation is for Rancher users who want to test out Rancher. - -Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. - -For Rancher v2.5+, the backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using [these steps.]({{}}/rancher/v2.5/en/backups/migrating-rancher) - -For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. - -| Environment Variable Key | Environment Variable Value | Description | -| -------------------------------- | -------------------------------- | ---- | -| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | -| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | - -> **Do you want to...** -> -> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.5/en/installation/options/custom-ca-root-certificate/). -> - Record all transactions with the Rancher API? See [API Auditing]({{}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log). - -Choose from the following options: - -### Option A: Default Self-Signed Certificate - -{{% accordion id="option-a" label="Click to expand" %}} - -If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself. - -Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. - -| Placeholder | Description | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `` | Your private registry URL and port. | -| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | - -As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher - -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts - --privileged \ - /rancher/rancher: -``` - -{{% /accordion %}} - -### Option B: Bring Your Own Certificate: Self-Signed - -{{% accordion id="option-b" label="Click to expand" %}} - -In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. - -> **Prerequisites:** -> From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. -> -> - The certificate files must be in PEM format. -> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting) - -After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container. - -| Placeholder | Description | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `` | The path to the directory containing your certificate files. | -| `` | The path to your full certificate chain. | -| `` | The path to the private key for your certificate. | -| `` | The path to the certificate authority's certificate. | -| `` | Your private registry URL and port. | -| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | - -As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - -v //:/etc/rancher/ssl/cert.pem \ - -v //:/etc/rancher/ssl/key.pem \ - -v //:/etc/rancher/ssl/cacerts.pem \ - -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher - -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts - --privileged \ - /rancher/rancher: -``` - -{{% /accordion %}} - -### Option C: Bring Your Own Certificate: Signed by Recognized CA - -{{% accordion id="option-c" label="Click to expand" %}} - -In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. - -> **Prerequisite:** The certificate files must be in PEM format. - -After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. - -| Placeholder | Description | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `` | The path to the directory containing your certificate files. | -| `` | The path to your full certificate chain. | -| `` | The path to the private key for your certificate. | -| `` | Your private registry URL and port. | -| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | - -> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. - -As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) - -``` -docker run -d --restart=unless-stopped \ - -p 80:80 -p 443:443 \ - --no-cacerts \ - -v //:/etc/rancher/ssl/cert.pem \ - -v //:/etc/rancher/ssl/key.pem \ - -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher - -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts - --privileged - /rancher/rancher: -``` - -{{% /accordion %}} - - - -> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.5/en/faq/telemetry/) during the initial login. - - -{{% /tab %}} -{{% /tabs %}} diff --git a/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/_index.md b/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/_index.md new file mode 100644 index 00000000000..81a30b69e84 --- /dev/null +++ b/content/rancher/v2.5/en/installation/other-installation-methods/air-gap/install-rancher/docker-install-commands/_index.md @@ -0,0 +1,130 @@ +--- +title: Docker Install Commands +weight: 1 +--- + +The Docker installation is for Rancher users who want to test out Rancher. + +Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a `docker run` command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. + +For Rancher v2.5+, the backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using [these steps.]({{}}/rancher/v2.5/en/backups/migrating-rancher) + +For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster. + +| Environment Variable Key | Environment Variable Value | Description | +| -------------------------------- | -------------------------------- | ---- | +| `CATTLE_SYSTEM_DEFAULT_REGISTRY` | `` | Configure Rancher server to always pull from your private registry when provisioning clusters. | +| `CATTLE_SYSTEM_CATALOG` | `bundled` | Configure Rancher server to use the packaged copy of Helm system charts. The [system charts](https://github.com/rancher/system-charts) repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These [Helm charts](https://github.com/rancher/system-charts) are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. | + +> **Do you want to...** +> +> - Configure custom CA root certificate to access your services? See [Custom CA root certificate]({{}}/rancher/v2.5/en/installation/options/custom-ca-root-certificate/). +> - Record all transactions with the Rancher API? See [API Auditing]({{}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/advanced/#api-audit-log). + +Choose from the following options: + +### Option A: Default Self-Signed Certificate + +{{% accordion id="option-a" label="Click to expand" %}} + +If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself. + +Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | + +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` + +{{% /accordion %}} + +### Option B: Bring Your Own Certificate: Self-Signed + +{{% accordion id="option-b" label="Click to expand" %}} + +In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher. + +> **Prerequisites:** +> From a computer with an internet connection, create a self-signed certificate using [OpenSSL](https://www.openssl.org/) or another method of your choice. +> +> - The certificate files must be in PEM format. +> - In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [Certificate Troubleshooting.]({{}}/rancher/v2.5/en/installation/other-installation-methods/single-node-docker/troubleshooting) + +After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the `-v` flag and provide the path to your certificates to mount them in your container. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | +| `` | The path to the certificate authority's certificate. | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | + +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -v //:/etc/rancher/ssl/cacerts.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged \ + /rancher/rancher: +``` + +{{% /accordion %}} + +### Option C: Bring Your Own Certificate: Signed by Recognized CA + +{{% accordion id="option-c" label="Click to expand" %}} + +In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings. + +> **Prerequisite:** The certificate files must be in PEM format. + +After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary. + +| Placeholder | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `` | The path to the directory containing your certificate files. | +| `` | The path to your full certificate chain. | +| `` | The path to the private key for your certificate. | +| `` | Your private registry URL and port. | +| `` | The release tag of the [Rancher version]({{}}/rancher/v2.5/en/installation/resources/chart-options/) that you want to install. | + +> **Note:** Use the `--no-cacerts` as argument to the container to disable the default CA certificate generated by Rancher. + +As of Rancher v2.5, privileged access is [required.](#privileged-access-for-rancher-v2-5) + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + --no-cacerts \ + -v //:/etc/rancher/ssl/cert.pem \ + -v //:/etc/rancher/ssl/key.pem \ + -e CATTLE_SYSTEM_DEFAULT_REGISTRY= \ # Set a default private registry to be used in Rancher + -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts + --privileged + /rancher/rancher: +``` + +{{% /accordion %}} + + + +> **Note:** If you don't intend to send telemetry data, opt out [telemetry]({{}}/rancher/v2.5/en/faq/telemetry/) during the initial login. + diff --git a/content/rancher/v2.5/en/installation/resources/feature-flags/_index.md b/content/rancher/v2.5/en/installation/resources/feature-flags/_index.md index 2294108e749..72509798b96 100644 --- a/content/rancher/v2.5/en/installation/resources/feature-flags/_index.md +++ b/content/rancher/v2.5/en/installation/resources/feature-flags/_index.md @@ -51,10 +51,10 @@ The below table shows the availability and default value for feature flags in Ra When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher. +### Enabling Features for Kubernetes Installs + > **Note:** Values set from the Rancher API will override the value passed in through the command line. -{{% tabs %}} -{{% tab "Kubernetes Install" %}} When installing Rancher with a Helm chart, use the `--features` option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list: ``` @@ -76,6 +76,24 @@ Here is an example of a command for passing in the feature flag names when rende The Helm 3 command is as follows: +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} + +``` +helm template rancher ./rancher-.tgz --output-dir . \ + --no-hooks \ # prevent files for Helm hooks from being generated + --namespace cattle-system \ + --set hostname= \ + --set rancherImage=/rancher/rancher \ + --set ingress.tls.source=secret \ + --set systemDefaultRegistry= \ # Set a default private registry to be used in Rancher + --set useBundledSystemChart=true # Use the packaged Rancher system charts + --set 'extraEnv[0].name=CATTLE_FEATURES' + --set 'extraEnv[0].value==true,=true' +``` +{{% /tab %}} +{{% tab "Rancher before v2.5.8" %}} + ``` helm template rancher ./rancher-.tgz --output-dir . \ --namespace cattle-system \ @@ -87,6 +105,8 @@ helm template rancher ./rancher-.tgz --output-dir . \ --set 'extraEnv[0].name=CATTLE_FEATURES' --set 'extraEnv[0].value==true,=true' ``` +{{% /tab %}} +{{% /tabs %}} The Helm 2 command is as follows: @@ -103,8 +123,8 @@ helm template ./rancher-.tgz --output-dir . \ --set 'extraEnv[0].value==true,=true' ``` -{{% /tab %}} -{{% tab "Docker Install" %}} +### Enabling Features for Docker Installs + When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list: ``` @@ -114,8 +134,6 @@ docker run -d -p 80:80 -p 443:443 \ --features==true,=true ``` -{{% /tab %}} -{{% /tabs %}} # Enabling Features with the Rancher UI diff --git a/content/rancher/v2.5/en/istio/configuration-reference/_index.md b/content/rancher/v2.5/en/istio/configuration-reference/_index.md index 50e55650a0e..79164a8f965 100644 --- a/content/rancher/v2.5/en/istio/configuration-reference/_index.md +++ b/content/rancher/v2.5/en/istio/configuration-reference/_index.md @@ -11,7 +11,7 @@ aliases: - [Selectors and Scrape Configs](#selectors-and-scrape-configs) - [Enable Istio with Pod Security Policies](#enable-istio-with-pod-security-policies) - [Additional Steps for Installing Istio on an RKE2 Cluster](#additional-steps-for-installing-istio-on-an-rke2-cluster) -- [Additional Steps for Canal Network Plug-in with Project Network Isolation](#additional-steps-for-canal-network-plug-in-with-project-network-isolation) +- [Additional Steps for Project Network Isolation](#additional-steps-for-project-network-isolation) ### Egress Support @@ -45,6 +45,6 @@ Refer to [this section.](./enable-istio-with-psp) Refer to [this section.](./rke2) -### Additional Steps for Canal Network Plug-in with Project Network Isolation +### Additional Steps for Project Network Isolation Refer to [this section.](./canal-and-project-network) \ No newline at end of file diff --git a/content/rancher/v2.5/en/istio/configuration-reference/canal-and-project-network/_index.md b/content/rancher/v2.5/en/istio/configuration-reference/canal-and-project-network/_index.md index 886d366e69b..77f82b11b3c 100644 --- a/content/rancher/v2.5/en/istio/configuration-reference/canal-and-project-network/_index.md +++ b/content/rancher/v2.5/en/istio/configuration-reference/canal-and-project-network/_index.md @@ -1,5 +1,5 @@ --- -title: Additional Steps for Canal Network Plug-in with Project Network Isolation +title: Additional Steps for Project Network Isolation weight: 4 aliases: - /rancher/v2.5/en/istio/v2.5/configuration-reference/canal-and-project-network @@ -7,8 +7,8 @@ aliases: In clusters where: -- The Canal network plug-in is in use. -- The Project Network Isolation option is enabled. +- You are using the Canal network plugin with Rancher before v2.5.8, or you are using Rancher v2.5.8+ with an any RKE network plug-in that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin +- The Project Network Isolation option is enabled - You install the Istio Ingress module The Istio Ingress Gateway pod won't be able to redirect ingress traffic to the workloads by default. This is because all the namespaces will be inaccessible from the namespace where Istio is installed. You have two options. diff --git a/content/rancher/v2.5/en/istio/setup/enable-istio-in-cluster/_index.md b/content/rancher/v2.5/en/istio/setup/enable-istio-in-cluster/_index.md index 3bedfae64cf..1f7f9546c31 100644 --- a/content/rancher/v2.5/en/istio/setup/enable-istio-in-cluster/_index.md +++ b/content/rancher/v2.5/en/istio/setup/enable-istio-in-cluster/_index.md @@ -11,7 +11,7 @@ aliases: >- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster. >- If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see [this section.]({{}}/rancher/v2.5/en/istio/v2.5/configuration-reference/enable-istio-with-psp) >- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.]({{}}/rancher/v2.5/en/istio/v2.5/configuration-reference/rke2/) ->- To install Istio in a cluster where the Canal network plug-in is in use and the Project Network isolation option is enabled, additional steps are required. For details, see [this section.]({{}}/rancher/v2.5/en/istio/v2.5/configuration-reference/canal-and-project-network) +>- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.]({{}}/rancher/v2.5/en/istio/v2.5/configuration-reference/canal-and-project-network) 1. From the **Cluster Explorer**, navigate to available **Charts** in **Apps & Marketplace** 1. Select the Istio chart from the rancher provided charts diff --git a/content/rancher/v2.5/en/logging/_index.md b/content/rancher/v2.5/en/logging/_index.md index 6aa6c4be2c5..36acadc4b50 100644 --- a/content/rancher/v2.5/en/logging/_index.md +++ b/content/rancher/v2.5/en/logging/_index.md @@ -13,10 +13,15 @@ aliases: - [Changes in Rancher v2.5](#changes-in-rancher-v2-5) - [Enabling Logging for Rancher Managed Clusters](#enabling-logging-for-rancher-managed-clusters) - [Uninstall Logging](#uninstall-logging) +- [Windows Support](#windows-support) - [Role-based Access Control](#role-based-access-control) - [Configuring the Logging Application](#configuring-the-logging-application) +- [Examples](#examples) - [Working with a Custom Docker Root Directory](#working-with-a-custom-docker-root-directory) - [Working with Taints and Tolerations](#working-with-taints-and-tolerations) +- [Logging v2 with SELinux](#logging-v2-with-selinux) +- [Additional Logging Sources](#additional-logging-sources) +- [Troubleshooting](#troubleshooting) # Changes in Rancher v2.5 @@ -56,6 +61,30 @@ You can enable the logging for a Rancher managed cluster by going to the Apps pa **Result** `rancher-logging` is uninstalled. +# Windows Support + +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} +As of Rancher v2.5.8, logging support for Windows clusters has been added and logs can be collected from Windows nodes. + +### Enabling and Disabling Windows Node Logging + +You can enable or disable Windows node logging by setting `global.cattle.windows.enabled` to either `true` or `false` in the `values.yaml`. +By default, Windows node logging will be enabled if the Cluster Explorer UI is used to install the logging application on a Windows cluster. +In this scenario, setting `global.cattle.windows.enabled` to `false` will disable Windows node logging on the cluster. +When disabled, logs will still be collected from Linux nodes within the Windows cluster. + +> Note: Currently an [issue](https://github.com/rancher/rancher/issues/32325) exists where Windows nodeAgents are not deleted when performing a `helm upgrade` after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed. + +{{% /tab %}} +{{% tab "Rancher v2.5.0-2.5.7" %}} +Clusters with Windows workers support exporting logs from Linux nodes, but Windows node logs are currently unable to be exported. +Only Linux node logs are able to be exported. + +To allow the logging pods to be scheduled on Linux nodes, tolerations must be added to the pods. Refer to the [Working with Taints and Tolerations](#working-with-taints-and-tolerations) section for details and an example. +{{% /tab %}} +{{% /tabs %}} + # Role-based Access Control Rancher logging has two roles, `logging-admin` and `logging-view`. @@ -189,9 +218,50 @@ spec: - "devteam-splunk" ``` +### Output to Syslog + +Let's say you wanted to send all logs in your cluster to an `syslog` server. First, we create a cluster output. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 + kind: ClusterOutput + metadata: + name: "example-syslog" + namespace: "cattle-logging-system" + spec: + syslog: + buffer: + timekey: 30s + timekey_use_utc: true + timekey_wait: 10s + flush_interval: 5s + format: + type: json + app_name_field: test + host: syslog.example.com + insecure: true + port: 514 + transport: tcp +``` + +Now that we have configured where we want the logs to go, let's configure all logs to go to that output. + +```yaml +apiVersion: logging.banzaicloud.io/v1beta1 + kind: ClusterFlow + metadata: + name: "all-logs" + namespace: cattle-logging-system + spec: + globalOutputRefs: + - "example-syslog" +``` + ### Unsupported Output -For the final example, we create an output to write logs to a destination that is not supported out of the box (e.g. syslog): +For the final example, we create an output to write logs to a destination that is not supported out of the box: + +> **Note on syslog** As of Rancher v2.5.4, `syslog` is a supported output. However, this example still provides an overview on using unsupported plugins. ```yaml apiVersion: v1 @@ -281,14 +351,14 @@ spec: Let's break down what is happening here. First, we create a deployment of a container that has the additional `syslog` plugin and accepts logs forwarded from another `fluentd`. Next we create an output configured as a forwarder to our deployment. The deployment `fluentd` will then forward all logs to the configured `syslog` destination. -> **Note on syslog** Official `syslog` support is coming in Rancher v2.5.4. However, this example still provides an overview on using unsupported plugins. - # Working with a Custom Docker Root Directory _Applies to v2.5.6+_ If using a custom Docker root directory, you can set `global.dockerRootDirectory` in `values.yaml`. This will ensure that the Logging CRs created will use your specified path rather than the default Docker `data-root` location. +Note that this only affects Linux nodes. +If there are any Windows nodes in the cluster, the change will not be applicable to those nodes. # Working with Taints and Tolerations @@ -298,11 +368,23 @@ Unless the pods have a `toleration` for that node's taint, they will run on othe Using `nodeSelector` gives pods an affinity towards certain nodes. Both provide choice for the what node(s) the pod will run on. + ### Default Implementation in Rancher's Logging Stack +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} +By default, Rancher taints all Linux nodes with `cattle.io/os=linux`, and does not taint Windows nodes. +The logging stack pods have `tolerations` for this taint, which enables them to run on Linux nodes. +Moreover, most logging stack pods run on Linux only and have a `nodeSelector` added to ensure they run on Linux nodes. + +{{% /tab %}} +{{% tab "Rancher v2.5.0-2.5.7" %}} By default, Rancher taints all Linux nodes with `cattle.io/os=linux`, and does not taint Windows nodes. The logging stack pods have `tolerations` for this taint, which enables them to run on Linux nodes. Moreover, we can populate the `nodeSelector` to ensure that our pods *only* run on Linux nodes. + +{{% /tab %}} +{{% /tabs %}} Let's look at an example pod YAML file with these settings... ```yaml @@ -323,11 +405,6 @@ spec: In the above example, we ensure that our pod only runs on Linux nodes, and we add a `toleration` for the taint we have on all of our Linux nodes. You can do the same with Rancher's existing taints, or with your own custom ones. -### Windows Support - -Clusters with Windows workers support exporting logs from Linux nodes, but Windows node logs are currently unable to be exported. -Only Linux node logs are able to be exported. - ### Adding NodeSelector Settings and Tolerations for Custom Taints If you would like to add your own `nodeSelector` settings, or if you would like to add `tolerations` for additional taints, you can pass the following to the chart's values. @@ -349,6 +426,40 @@ fluentbit_tolerations: # insert tolerations list for fluentbit containers only... ``` + +# Logging v2 with SELinux + +_Available as of v2.5.8_ + +> **Requirements:** Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. + +To use Logging v2 with SELinux, we recommend installing the `rancher-selinux` RPM according to the instructions on [this page.]({{}}/rancher/v2.5/en/security/selinux/#installing-the-rancher-selinux-rpm) + +Then you will need to configure the logging application to work with SELinux as shown in [this section.]({{}}/rancher/v2.5/en/security/selinux/#configuring-the-logging-application-to-work-with-selinux) + +# Additional Logging Sources + +By default, Rancher collects logs for [control plane components](https://kubernetes.io/docs/concepts/overview/components/#control-plane-components) and [node components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for all cluster types. +In some cases, Rancher may be able to collect additional logs. + +The following table summarizes the sources where additional logs may be collected for each node types: + +| Logging Source | Linux Nodes (including in Windows cluster) | Windows Nodes | +| --- | --- | ---| +| RKE | ✓ | ✓ | +| RKE2 | ✓ | | +| K3s | ✓ | | +| AKS | ✓ | | +| EKS | ✓ | | +| GKE | ✓ | | + +To enable hosted Kubernetes providers as additional logging sources, go to **Cluster Explorer > Logging > Chart Options** and select the **Enable enhanced cloud provider logging** option. +When enabled, Rancher collects all additional node and control plane logs the provider has made available, which may vary between providers. +If you're already using a cloud provider's own logging solution such as AWS CloudWatch or Google Cloud operations suite (formerly Stackdriver), it is not necessary to enable this option as the native solution will have unrestricted access to all logs. + + # Troubleshooting ### The `cattle-logging` Namespace Being Recreated diff --git a/content/rancher/v2.5/en/monitoring-alerting/_index.md b/content/rancher/v2.5/en/monitoring-alerting/_index.md index 611c9242132..e45f6b8a830 100644 --- a/content/rancher/v2.5/en/monitoring-alerting/_index.md +++ b/content/rancher/v2.5/en/monitoring-alerting/_index.md @@ -31,6 +31,7 @@ For more information about upgrading the Monitoring app in Rancher 2.5, please r - [About Prometheus](#about-prometheus) - [Enable Monitoring](#enable-monitoring) - [Default Alerts, Targets, and Grafana Dashboards](#default-alerts-targets-and-grafana-dashboards) +- [Windows Cluster Support](#windows-cluster-support) - [Using Monitoring](#using-monitoring) - [Grafana UI](#grafana-ui) - [Prometheus UI](#prometheus-ui) @@ -61,6 +62,10 @@ As an [administrator]({{}}/rancher/v2.5/en/admin-settings/rbac/global-p > - Make sure your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. A breakdown of the resource limits and requests is [here.](#setting-resource-limits-and-requests) > - When installing monitoring on an RKE cluster using RancherOS or Flatcar Linux nodes, change the etcd node certificate directory to `/opt/rke/etc/kubernetes/ssl`. +{{% tabs %}} +{{% tab "Rancher v2.5.8" %}} + +### Enable Monitoring for use without SSL 1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.** 1. Click **Apps.** @@ -70,6 +75,46 @@ As an [administrator]({{}}/rancher/v2.5/en/admin-settings/rbac/global-p **Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace. +### Enable Monitoring for use with SSL + +1. Follow the steps on [this page]({{}}/rancher/v2.5/en/k8s-in-rancher/secrets/) to create a secret in order for SSL to be used for alerts. + - The secret should be created in the `cattle-monitoring-system` namespace. If it doesn't exist, create it first. + - Add the `ca`, `cert`, and `key` files to the secret. +1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.** +1. Click **Apps.** +1. Click the `rancher-monitoring` app. +1. Click **Alerting**. +1. Click **Additional Secrets** and add the secrets created earlier. + +**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace. + +When [creating a receiver,]({{}}/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/#creating-receivers-in-the-rancher-ui) SSL-enabled receivers such as email or webhook will have a **SSL** section with fields for **CA File Path**, **Cert File Path**, and **Key File Path**. Fill in these fields with the paths to each of `ca`, `cert`, and `key`. The path will be of the form `/etc/alertmanager/secrets/name-of-file-in-secret`. + +For example, if you created a secret with these key-value pairs: + +```yaml +ca.crt=`base64-content` +cert.pem=`base64-content` +key.pfx=`base64-content` +``` + +Then **Cert File Path** would be set to `/etc/alertmanager/secrets/cert.pem`. + +{{% /tab %}} +{{% tab "Rancher v2.5.0-2.5.7" %}} + +1. In the Rancher UI, go to the cluster where you want to install monitoring and click **Cluster Explorer.** +1. Click **Apps.** +1. Click the `rancher-monitoring` app. +1. Optional: Click **Chart Options** and configure alerting, Prometheus and Grafana. For help, refer to the [configuration reference.](./configuration) +1. Scroll to the bottom of the Helm chart README and click **Install.** + +**Result:** The monitoring app is deployed in the `cattle-monitoring-system` namespace. + +{{% /tab %}} + +{{% /tabs %}} + ### Default Alerts, Targets, and Grafana Dashboards By default, Rancher Monitoring deploys exporters (such as [node-exporter](https://github.com/prometheus/node_exporter) and [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics)) as well as default Prometheus alerts and Grafana dashboards (curated by the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project) onto a cluster. @@ -84,6 +129,16 @@ To see the default dashboards, go to the [Grafana UI.](#grafana-ui) In the left To configure Prometheus resources from the Rancher UI, click **Apps & Marketplace > Monitoring** in the upper left corner. +# Windows Cluster Support + +_Available as of v2.5.8_ + +When deployed onto an RKE1 Windows cluster, Monitoring V2 will now automatically deploy a [windows-exporter](https://github.com/prometheus-community/windows_exporter) DaemonSet and set up a ServiceMonitor to collect metrics from each of the deployed Pods. This will populate Prometheus with `windows_` metrics that are akin to the `node_` metrics exported by [node_exporter](https://github.com/prometheus/node_exporter) for Linux hosts. + +To be able to fully deploy Monitoring V2 for Windows, all of your Windows hosts must have a minimum [wins](https://github.com/rancher/wins) version of v0.1.0. + +For more details on how to upgrade wins on existing Windows hosts, refer to the section on [Windows cluster support for Monitoring V2.](./windows-clusters) + # Using Monitoring Installing `rancher-monitoring` makes the following dashboards available from the Rancher UI. @@ -158,6 +213,8 @@ For more information on configuring Alertmanager in Rancher, see [this page.](./ **Result:** `rancher-monitoring` is uninstalled. +> **Note on Persistent Grafana Dashboards:** For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster. + # Setting Resource Limits and Requests The resource requests and limits can be configured when installing `rancher-monitoring`. diff --git a/content/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/_index.md b/content/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/_index.md index febc6aa22d3..ba0c63dac06 100644 --- a/content/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/_index.md +++ b/content/rancher/v2.5/en/monitoring-alerting/configuration/alertmanager/_index.md @@ -20,6 +20,8 @@ The [Alertmanager Config](https://prometheus.io/docs/alerting/latest/configurati - [Opsgenie](#opsgenie) - [Webhook](#webhook) - [Custom](#custom) + - [Teams](#teams) + - [SMS](#sms) - [Route Configuration](#route-configuration) - [Receiver](#receiver) - [Grouping](#grouping) @@ -70,23 +72,41 @@ To create notification receivers in the Rancher UI, The notification integrations are configured with the `receiver`, which is explained in the [Prometheus documentation.](https://prometheus.io/docs/alerting/latest/configuration/#receiver) +### Native vs. Non-native Receivers + +By default, AlertManager provides native integration with some receivers, which are listed in [this section.](https://prometheus.io/docs/alerting/latest/configuration/#receiver) All natively supported receivers are configurable through the Rancher UI. + +For notification mechanisms not natively supported by AlertManager, integration is achieved using the [webhook receiver.](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config) A list of third-party drivers providing such integrations can be found [here.](https://prometheus.io/docs/operating/integrations/#alertmanager-webhook-receiver) Access to these drivers, and their associated integrations, is provided through the Alerting Drivers app. Once enabled, configuring non-native receivers can also be done through the Rancher UI. + +Currently the Rancher Alerting Drivers app provides access to the following integrations: +- Microsoft Teams, based on the [prom2teams](https://github.com/idealista/prom2teams) driver +- SMS, based on the [Sachet](https://github.com/messagebird/sachet) driver + +### Changes in Rancher v2.5.8 + +Rancher v2.5.8 added Microsoft Teams and SMS as configurable receivers in the Rancher UI. + +### Changes in Rancher v2.5.4 + Rancher v2.5.4 introduced the capability to configure receivers by filling out forms in the Rancher UI. {{% tabs %}} -{{% tab "Rancher v2.5.4+" %}} +{{% tab "Rancher v2.5.8" %}} The following types of receivers can be configured in the Rancher UI: -- Slack -- Email -- PagerDuty -- Opsgenie -- Webhook -- Custom +- Slack +- Email +- PagerDuty +- Opsgenie +- Webhook +- Custom +- Teams +- SMS The custom receiver option can be used to configure any receiver in YAML that cannot be configured by filling out the other forms in the Rancher UI. -### Slack +# Slack | Field | Type | Description | |------|--------------|------| @@ -95,7 +115,7 @@ The custom receiver option can be used to configure any receiver in YAML that ca | 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). | -### Email +# Email | Field | Type | Description | |------|--------------|------| @@ -112,7 +132,7 @@ SMTP options: | Username | String | Enter a username to authenticate with the SMTP server. | | Password | String | Enter a password to authenticate with the SMTP server. | -### PagerDuty +# PagerDuty | Field | Type | Description | |------|------|-------| @@ -121,7 +141,7 @@ SMTP options: | 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). | -### Opsgenie +# Opsgenie | Field | Description | |------|-------------| @@ -136,7 +156,7 @@ Opsgenie Responders: | Type | String | Schedule, Team, User, or Escalation. For more information on alert responders, refer to the [Opsgenie documentation.](https://docs.opsgenie.com/docs/alert-recipients-and-teams) | | Send To | String | Id, Name, or Username of the Opsgenie recipient. | -### Webhook +# Webhook | Field | Description | |-------|--------------| @@ -144,7 +164,163 @@ Opsgenie Responders: | Proxy URL | Proxy for the webhook notification. | | Enable Send Resolved Alerts | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | -### Custom + + +# Custom + +The YAML provided here will be directly appended to your receiver within the Alertmanager Config Secret. + +# Teams + +### Enabling the Teams Receiver for Rancher Managed Clusters + +The Teams receiver is not a native receiver and must be enabled before it can be used. You can enable the Teams receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the Teams option selected. + +1. In the Rancher UI, go to the cluster where you want to install rancher-alerting-drivers and click **Cluster Explorer**. +1. Click **Apps**. +1. Click the **Alerting Drivers** app. +1. Click the **Helm Deploy Options** tab +1. Select the **Teams** option and click **Install**. +1. Take note of the namespace used as it will be required in a later step. + +### Configure the Teams Receiver + +The Teams receiver can be configured by updating its ConfigMap. For example, the following is a minimal Teams receiver configuration. + +```yaml +[Microsoft Teams] +teams-instance-1: https://your-teams-webhook-url +``` + +When configuration is complete, add the receiver using the steps in [this section](#creating-receivers-in-the-rancher-ui). + +Use the example below as the URL where: + +- `ns-1` is replaced with the namespace where the `rancher-alerting-drivers` app is installed + +```yaml +url: http://rancher-alerting-drivers-prom2teams.ns-1.svc:8089/v2/teams-instance-1 +``` + + + +# SMS + +### Enabling the SMS Receiver for Rancher Managed Clusters + +The SMS receiver is not a native receiver and must be enabled before it can be used. You can enable the SMS receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the SMS option selected. + +1. In the Rancher UI, go to the cluster where you want to install rancher-alerting-drivers and click **Cluster Explorer**. +1. Click **Apps**. +1. Click the **Alerting Drivers** app. +1. Click the **Helm Deploy Options** tab +1. Select the **SMS** option and click **Install**. +1. Take note of the namespace used as it will be required in a later step. + +### Configure the SMS Receiver + +The SMS receiver can be configured by updating its ConfigMap. For example, the following is a minimal SMS receiver configuration. + +```yaml +providers: + telegram: + token: 'your-token-from-telegram' + +receivers: +- name: 'telegram-receiver-1' + provider: 'telegram' + to: + - '123456789' +``` + +When configuration is complete, add the receiver using the steps in [this section](#creating-receivers-in-the-rancher-ui). + +Use the example below as the name and URL, where: + +- the name assigned to the receiver, e.g. `telegram-receiver-1`, must match the name in the `receivers.name` field in the ConfigMap, e.g. `telegram-receiver-1` +- `ns-1` in the URL is replaced with the namespace where the `rancher-alerting-drivers` app is installed + +```yaml +name: telegram-receiver-1 +url http://rancher-alerting-drivers-sachet.ns-1.svc:9876/alert +``` + + + +{{% /tab %}} + +{{% tab "Rancher v2.5.4-2.5.7" %}} + +The following types of receivers can be configured in the Rancher UI: + +- Slack +- Email +- PagerDuty +- Opsgenie +- Webhook +- Custom + +The custom receiver option can be used to configure any receiver in YAML that cannot be configured by filling out the other forms in the Rancher UI. + +### Slack {#slack-254-257} + +| 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: `#`. | +| 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). | + +### Email {#email-254-257} + +| 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). | + +SMTP options: + +| Field | Type | Description | +|------|--------------|------| +| Sender | String | Enter an email address available on your SMTP mail server that you want to send the notification from. | +| Host | String | Enter the IP address or hostname for your SMTP server. Example: `smtp.email.com`. | +| Use TLS | Bool | Use TLS for encryption. | +| Username | String | Enter a username to authenticate with the SMTP server. | +| Password | String | Enter a password to authenticate with the SMTP server. | + +### PagerDuty {#pagerduty-254-257} + +| Field | Type | Description | +|------|------|-------| +| 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). | + +### Opsgenie {#opsgenie-254-257} + +| Field | Description | +|------|-------------| +| API Key | For instructions to get an API key, refer to the [Opsgenie documentation.](https://docs.opsgenie.com/docs/api-key-management) | +| Proxy URL | Proxy for the Opsgenie notifications. | +| Enable Send Resolved Alerts | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | + +Opsgenie Responders: + +| Field | Type | Description | +|-------|------|--------| +| Type | String | Schedule, Team, User, or Escalation. For more information on alert responders, refer to the [Opsgenie documentation.](https://docs.opsgenie.com/docs/alert-recipients-and-teams) | +| Send To | String | Id, Name, or Username of the Opsgenie recipient. | + +### Webhook {#webhook-1} + +| Field | Description | +|-------|--------------| +| URL | Webhook URL for the app of your choice. | +| Proxy URL | Proxy for the webhook notification. | +| Enable Send Resolved Alerts | Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage). | + +### Custom {#custom-254-257} The YAML provided here will be directly appended to your receiver within the Alertmanager Config Secret. @@ -237,4 +413,4 @@ spec: # key: string ``` -For more information on enabling alerting for `rancher-cis-benchmark`, see [this section.]({{}}/rancher/v2.5/en/cis-scans/v2.5/#enabling-alerting-for-rancher-cis-benchmark) \ No newline at end of file +For more information on enabling alerting for `rancher-cis-benchmark`, see [this section.]({{}}/rancher/v2.5/en/cis-scans/v2.5/#enabling-alerting-for-rancher-cis-benchmark) diff --git a/content/rancher/v2.5/en/monitoring-alerting/persist-grafana/_index.md b/content/rancher/v2.5/en/monitoring-alerting/persist-grafana/_index.md index d4fe2d1fe15..95d45176ce5 100644 --- a/content/rancher/v2.5/en/monitoring-alerting/persist-grafana/_index.md +++ b/content/rancher/v2.5/en/monitoring-alerting/persist-grafana/_index.md @@ -7,13 +7,93 @@ aliases: To allow the Grafana dashboard to persist after the Grafana instance restarts, add the dashboard configuration JSON into a ConfigMap. ConfigMaps also allow the dashboards to be deployed with a GitOps or CD based approach. This allows the dashboard to be put under version control. +- [Creating a Persistent Grafana Dashboard](#creating-a-persistent-grafana-dashboard) +- [Known Issues](#known-issues) + +# Creating a Persistent Grafana Dashboard + +{{% tabs %}} +{{% tab "Rancher v2.5.8+" %}} + +> **Prerequisites:** +> +> - The monitoring application needs to be installed. +> - To create the persistent dashboard, you must have at least the **Manage Config Maps** Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the `monitoring-dashboard-edit` or `monitoring-dashboard-admin` Kubernetes native RBAC Roles exposed by the Monitoring chart. +> - To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a [project-member role.]({{}}/rancher/v2.5/en/monitoring-alerting/rbac/#users-with-rancher-cluster-manager-based-permissions) + +### 1. Get the JSON model of the dashboard that you want to persist + +To create a persistent dashboard, you will need to get the JSON model of the dashboard you want to persist. You can use a premade dashboard or build your own. + +To use a premade dashboard, go to [https://grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards), open up its detail page, and click on the **Download JSON** button to get the JSON model for the next step. + +To use your own dashboard: + +1. Click on the link to open Grafana. From the **Cluster Explorer,** click **Cluster Explorer > Monitoring.** +1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. + + > **Note:** Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart. +1. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click **JSON Model.** +1. Copy the JSON data structure that appears. + +### 2. Create a ConfigMap using the Grafana JSON model + +Create a ConfigMap in the namespace that contains your Grafana Dashboards (e.g. cattle-dashboards by default). + +The ConfigMap should look like this: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + grafana_dashboard: "1" + name: + namespace: cattle-dashboards # Change if using a non-default namespace +data: + .json: |- + +``` + +By default, Grafana is configured to watch all ConfigMaps with the `grafana_dashboard` label within the `cattle-dashboards` namespace. + +To specify that you would like Grafana to watch for ConfigMaps across all namespaces, refer to [this section.](#configuring-namespaces-for-the-grafana-dashboard-configmap) + +To create the ConfigMap in the Rancher UI, + +1. Go to the Cluster Explorer. +1. Click **Core > ConfigMaps**. +1. Click **Create**. +1. Set up the key-value pairs similar to the example above. When entering the value for `.json`, click **Read from File** to upload the JSON data model as the value. +1. Click **Create**. + +**Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted. + +Dashboards that are persisted using ConfigMaps cannot be deleted or edited from the Grafana UI. + +If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap. + +### Configuring Namespaces for the Grafana Dashboard ConfigMap + +To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set: + +``` +grafana.sidecar.dashboards.searchNamespace=ALL +``` + +Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in `grafana.dashboards.namespace`, which defaults to `cattle-dashboards`. + +{{% /tab %}} +{{% tab "Rancher v2.5.0-v2.5.8" %}} > **Prerequisites:** > > - The monitoring application needs to be installed. > - You must have the cluster-admin ClusterRole permission. 1. Open the Grafana dashboard. From the **Cluster Explorer,** click **Cluster Explorer > Monitoring.** -1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. (Regardless of who has the password, cluster administrator permission in Rancher is still required access the Grafana instance.) Alternative credentials can also be supplied on deploying or upgrading the chart. +1. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is `admin/prom-operator`. Alternative credentials can also be supplied on deploying or upgrading the chart. + + > **Note:** Regardless of who has the password, cluster administrator permission in Rancher is still required to access the Grafana instance. 1. Go to the dashboard that you want to persist. In the top navigation menu, go to the dashboard settings by clicking the gear icon. 1. In the left navigation menu, click **JSON Model.** 1. Copy the JSON data structure that appears. @@ -35,3 +115,18 @@ To allow the Grafana dashboard to persist after the Grafana instance restarts, a **Result:** After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted. Dashboards that are persisted using ConfigMaps cannot be deleted from the Grafana UI. If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap. + +To prevent the persistent dashboard from being deleted when Monitoring v2 is uninstalled, add the following annotation to the `cattle-dashboards` namespace: + +``` +helm.sh/resource-policy: "keep" +``` + +{{% /tab %}} +{{% /tabs %}} + +# Known Issues + +For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the `cattle-dashboards` namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation `helm.sh/resource-policy: "keep"`. + +This annotation will be added by default in the new monitoring chart released by Rancher v2.5.8, but it still needs to be manually applied for users of earlier Rancher versions. diff --git a/content/rancher/v2.5/en/monitoring-alerting/rbac/_index.md b/content/rancher/v2.5/en/monitoring-alerting/rbac/_index.md index edb14fff084..bd43af05add 100644 --- a/content/rancher/v2.5/en/monitoring-alerting/rbac/_index.md +++ b/content/rancher/v2.5/en/monitoring-alerting/rbac/_index.md @@ -7,7 +7,18 @@ aliases: --- This section describes the expectations for RBAC for Rancher Monitoring. -## Cluster Admins +- [Cluster Admins](#cluster-admins) +- [Users with Kubernetes ClusterRole-based Permissions](#users-with-kubernetes-clusterrole-based-permissions) + - [Users with Kubernetes Admin/Edit Permissions](#users-with-kubernetes-admin-edit-permissions) + - [Users with Kubernetes View Permissions](#users-with-kubernetes-view-permissions) + - [Additional Monitoring Roles](#additional-monitoring-roles) + - [Additional Monitoring ClusterRoles](#additional-monitoring-clusterroles) +- [Additional Monitoring Roles](#additional-monitoring-roles) +- [Users with Rancher Cluster Manager Based Permissions](#users-with-rancher-cluster-manager-based-permissions) + - [Differences in 2.5.x](#differences-in-2-5-x) + - [Assigning Additional Access](#assigning-additional-access) + +# Cluster Admins By default, only those with the cluster-admin `ClusterRole` should be able to: @@ -18,7 +29,7 @@ By default, only those with the cluster-admin `ClusterRole` should be able to: - Persist new Grafana dashboards or datasources via creating ConfigMaps in the appropriate namespace - Expose certain Prometheus metrics to the k8s Custom Metrics API for HPA via a Secret in the `cattle-monitoring-system` namespace -## Users with k8s ClusterRole-based Permissions +# Users with Kubernetes ClusterRole-based Permissions The `rancher-monitoring` chart installs the following three `ClusterRoles`. By default, they aggregate into the corresponding k8s `ClusterRoles`: @@ -37,25 +48,27 @@ These `ClusterRoles` provide different levels of access to the Monitoring CRDs b On a high level, the following permissions are assigned by default as a result. -### Users with k8s Admin / Edit Permissions +### Users with Kubernetes Admin/Edit Permissions -Only those with the the cluster-admin / admin / edit `ClusterRole` should be able to: +Only those with the the cluster-admin, admin or edit `ClusterRole` should be able to: - Modify the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs - Modify the alerting / recording rules of a Prometheus deployment via PrometheusRules CRs -### Users with k8s View Permissions +### Users with Kubernetes View Permissions -Only those with who have some k8s `ClusterRole` should be able to: +Only those with who have some Kubernetes `ClusterRole` should be able to: - View the configuration of Prometheuses that are deployed within the cluster - View the configuration of Alertmanagers that are deployed within the cluster - View the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs -- View the alerting / recording rules of a Prometheus deployment via PrometheusRules CRs +- View the alerting/recording rules of a Prometheus deployment via PrometheusRules CRs -## Additional Monitoring Roles +### Additional Monitoring Roles -Monitoring also creates six additional `Roles` that are not assigned to users by default but are created within the cluster. Admins should use these roles to provide more fine-grained access to users: +Monitoring also creates additional `Roles` that are not assigned to users by default but are created within the cluster. They can be bound to a namespace by deploying a RoleBinding that references it. + +Admins should use these roles to provide more fine-grained access to users: | Role | Purpose | | ------------------------------| ---------------------------| @@ -66,10 +79,20 @@ Monitoring also creates six additional `Roles` that are not assigned to users by | monitoring-dashboard-edit | Allow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster. | | monitoring-dashboard-view | Allow admins to assign roles to users to be able to view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster. | -## Users with Rancher Cluster Manager Based Permissions +### Additional Monitoring ClusterRoles + +Monitoring also creates additional `ClusterRoles` that are not assigned to users by default but are created within the cluster. They are not aggregated by default but can be bound to a namespace by deploying a RoleBinding that references it. + +| Role | Purpose | +| ------------------------------| ---------------------------| +| monitoring-ui-view | _Available as of Monitoring v2 14.5.100+_ Provides read-only access to external Monitoring UIs by giving a user permission to list the Prometheus, Alertmanager, and Grafana endpoints and make GET requests to Prometheus, Grafana, and Alertmanager UIs through the Rancher proxy. | + +# Users with Rancher Cluster Manager Based Permissions The relationship between the default roles deployed by Rancher Cluster Manager (i.e. cluster-owner, cluster-member, project-owner, project-member), the default k8s roles, and the roles deployed by the rancher-monitoring chart are detailed in the table below: +
Default Rancher Permissions and Corresponding Kubernetes ClusterRoles
+ | Cluster Manager Role | k8s Role | Monitoring ClusterRole / Role | ClusterRoleBinding or RoleBinding? | | --------- | --------- | --------- | --------- | | cluster-owner | cluster-admin | N/A | ClusterRoleBinding | @@ -77,6 +100,16 @@ The relationship between the default roles deployed by Rancher Cluster Manager ( | project-owner | edit | monitoring-admin | RoleBinding within Project namespace | | project-member | view | monitoring-edit | RoleBinding within Project namespace | +In addition to these default Roles, the following additional Rancher project roles can be applied to members of your Cluster to provide additional access to Monitoring. These Rancher Roles will be tied to ClusterRoles deployed by the Monitoring chart: + +
Non-default Rancher Permissions and Corresponding Kubernetes ClusterRoles
+ +| Cluster Manager Role | Kubernetes ClusterRole | Available In Rancher From | Available in Monitoring v2 From | +|--------------------------|-------------------------------|-------|------| +| View Monitoring* | [monitoring-ui-view](#monitoring-ui-view) | 2.4.8+ | 9.4.204+ | + +\* A User bound to the **View Monitoring** Rancher Role only has permissions to access external Monitoring UIs if provided links to those UIs. In order to access the Monitoring Pane on Cluster Explorer to get those links, the User must be a Project Member of at least one Project. + ### Differences in 2.5.x Users with the project-member or project-owners roles assigned will not be given access to either Prometheus or Grafana in Rancher 2.5.x since we only create Grafana or Prometheus on a cluster-level. diff --git a/content/rancher/v2.5/en/monitoring-alerting/windows-clusters/_index.md b/content/rancher/v2.5/en/monitoring-alerting/windows-clusters/_index.md new file mode 100644 index 00000000000..1f894566a31 --- /dev/null +++ b/content/rancher/v2.5/en/monitoring-alerting/windows-clusters/_index.md @@ -0,0 +1,57 @@ +--- +title: Windows Cluster Support for Monitoring V2 +shortTitle: Windows Clusters +weight: 5 +--- + +_Available as of v2.5.8_ + +Starting at Monitoring V2 14.5.100 (used by default in Rancher 2.5.8), Monitoring V2 can now be deployed on a Windows cluster and will scrape metrics from Windows nodes using [prometheus-community/windows_exporter](https://github.com/prometheus-community/windows_exporter) (previously named `wmi_exporter`). + +- [Comparison to Monitoring V1](#comparison-to-monitoring-v1) +- [Cluster Requirements](#cluster-requirements) + - [Upgrading Existing Clusters to wins v0.1.0](#upgrading-existing-clusters-to-wins-v0-1-0) + +# Comparison to Monitoring V1 + +Unlike Monitoring V1 for Windows, metrics collected by `windows_exporter` will be labeled as `windows_` instead of `wmi_` in accordance to a naming change from upstream from `wmi_exporter` to `windows_exporter`. + +In addition, Monitoring V2 for Windows will no longer require users to keep port 9796 open on Windows hosts since the host metrics will published directly onto a port exposed on the windows-exporter Pod. This feature was powered by recent changes made by `wins` v0.1.0 to support publishing ports exposed on the hostNetwork on Pods that use wins to run a privileged Windows binary as a host process. + +# Cluster Requirements + +Monitoring V2 for Windows can only scrape metrics from Windows hosts that have a minimum `wins` version of v0.1.0. To be able to fully deploy Monitoring V2 for Windows, all of your hosts must meet this requirement. + +If you provision a fresh RKE1 cluster in Rancher 2.5.8, your cluster should already meet this requirement. + +### Upgrading Existing Clusters to wins v0.1.0 + +If the cluster was provisioned before Rancher 2.5.8 (even if the current Rancher version is 2.5.8), you will not be able to successfully deploy Monitoring V2 for Windows until you upgrade the wins version on each host to at least v0.1.0. + +To facilitate this upgrade, Rancher 2.5.8 has released a brand new Helm chart called `rancher-wins-upgrader`. + +> **Prerequisite:** Make sure Monitoring V1 for Windows is uninstalled. + +1. Deploy `rancher-wins-upgrader` with the following override: + ```yaml + # Masquerading bootstraps the wins-upgrader installation via + # a previously whitelisted process path since the normal install path, + # c:\etc\rancher\wins\wins-upgrade.exe is not normally whitelisted. + # In this case, we are using the previously whitelisted process + # path used by Monitoring V1. + masquerade: + enabled: true + as: c:\\etc\wmi-exporter\wmi-exporter.exe + ``` + > **Note for Non-Default Windows Prefix Path:** If you set up the RKE cluster with a `cluster.yml` that has a non-default `win_prefix_path`, you will need to update the `masquerade.as` field with your prefix path in place of `c:\\`. + > + > For example, if you have `win_prefix_path: 'c:\host\opt\'`, then you will need to set `as: c:\host\opt\etc\wmi-exporter\wmi-exporter.exe`. +2. Once all your hosts have been successfully upgraded, please ensure that you deploy the Helm chart once again with default values to avoid conflicts with the following settings: + ```yaml + masquerade: + enabled: false + ``` + +**Result:** The hosts are ready for Monitoring V2 to be installed. You may choose to uninstall the `rancher-wins-upgrader` chart or keep it in your cluster to facilitate future upgrades. + +For more information on how it can be used, please see the [README.md](https://github.com/rancher/wins/blob/master/charts/rancher-wins-upgrader/README.md) of the chart. diff --git a/content/rancher/v2.5/en/security/_index.md b/content/rancher/v2.5/en/security/_index.md index a50954a1fb2..8586f78b957 100644 --- a/content/rancher/v2.5/en/security/_index.md +++ b/content/rancher/v2.5/en/security/_index.md @@ -25,6 +25,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: - [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) - [The CIS Benchmark and self-assessment](#the-cis-benchmark-and-self-assessment) - [Third-party penetration test reports](#third-party-penetration-test-reports) @@ -46,6 +47,12 @@ When Rancher runs a CIS security scan on a cluster, it generates a report showin For details, refer to the section on [security scans.]({{}}/rancher/v2.5/en/cis-scans) +### SELinux RPM + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. + +We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: `rancher-selinux` and `rke2-selinux`. For details, see [this page.]({{}}/rancher/v2.5/en/security/selinux) + ### Rancher Hardening Guide The Rancher Hardening Guide is based on controls and best practices found in the CIS Kubernetes Benchmark from the Center for Internet Security. diff --git a/content/rancher/v2.5/en/security/rancher-2.5/_index.md b/content/rancher/v2.5/en/security/rancher-2.5/_index.md index 3b7eb986652..1cc1abf1372 100644 --- a/content/rancher/v2.5/en/security/rancher-2.5/_index.md +++ b/content/rancher/v2.5/en/security/rancher-2.5/_index.md @@ -6,6 +6,15 @@ weight: 1 Rancher v2.5 introduced the capability to deploy Rancher on any Kubernetes cluster. For that reason, we now provide separate security hardening guides for Rancher deployments on each of Rancher's Kubernetes distributions. +- [Rancher Kubernetes Distributions](#rancher-kubernetes-distributions) +- [Hardening Guides and Benchmark Versions](#hardening-guides-and-benchmark-versions) + - [RKE Guides](#rke-guides) + - [RKE2 Guides](#rke2-guides) + - [K3s Guides](#k3s) +- [Rancher with SELinux](#rancher-with-selinux) + +# Rancher Kubernetes Distributions + Rancher has the following Kubernetes distributions: - [**RKE,**]({{}}/rke/latest/en/) Rancher Kubernetes Engine, is a CNCF-certified Kubernetes distribution that runs entirely within Docker containers. @@ -14,7 +23,7 @@ Rancher has the following Kubernetes distributions: To harden a Kubernetes cluster outside of Rancher's distributions, refer to your Kubernetes provider docs. -# Guides +# Hardening Guides and Benchmark Versions These guides have been tested along with the Rancher v2.5 release. Each self-assessment guide is accompanied with a hardening guide and tested on a specific Kubernetes version and CIS benchmark version. If a CIS benchmark has not been validated for your Kubernetes version, you can choose to use the existing guides until a newer version is added. @@ -33,4 +42,15 @@ Kubernetes v1.18 | CIS v1.5 | [Link](https://docs.rke2.io/security/cis_self_asse ### K3s Guides -The K3s security guides will be added soon. +Kubernetes Version | CIS Benchmark Version | Self Assessment Guide | Hardening Guide +---|---|---|--- +Kubernetes v1.17, v1.18, & v1.19 | CIS v1.5 | [Link]({{}}/k3s/latest/en/security/self_assessment/) | [Link]({{}}/k3s/latest/en/security/hardening_guide/) + + +# Rancher with SELinux + +_Available as of v2.5.8_ + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. + +To use Rancher with SELinux, we recommend installing the `rancher-selinux` RPM according to the instructions on [this page.]({{}}/rancher/v2.5/en/security/selinux/#installing-the-rancher-selinux-rpm) \ No newline at end of file diff --git a/content/rancher/v2.5/en/security/selinux/_index.md b/content/rancher/v2.5/en/security/selinux/_index.md new file mode 100644 index 00000000000..fe707e064e2 --- /dev/null +++ b/content/rancher/v2.5/en/security/selinux/_index.md @@ -0,0 +1,84 @@ +--- +title: SELinux RPM +weight: 4 +--- + +_Available as of v2.5.8_ + +[Security-Enhanced Linux (SELinux)](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) is a security enhancement to Linux. + +Developed by Red Hat, it is an implementation of mandatory access controls (MAC) on Linux. Mandatory access controls allow an administrator of a system to define how applications and users can access different resources such as files, devices, networks and inter-process communication. SELinux also enhances security by making an OS restrictive by default. + +After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. + +We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: `rancher-selinux` and `rke2-selinux`. + +- [rancher-selinux](#rancher-selinux) +- [rke2-selinux](#rke2-selinux) +- [Installing the rancher-selinux RPM](#installing-the-rancher-selinux-rpm) +- [Configuring the Logging Application to Work with SELinux](#configuring-the-logging-application-to-work-with-selinux) + +# rancher-selinux + +To allow Rancher to work with SELinux, some functionality has to be manually enabled for the SELinux nodes. To help with that, Rancher provides a SELinux RPM. + +As of v2.5.8, the `rancher-selinux` RPM only contains policies for the [rancher-logging application.](https://github.com/rancher/charts/tree/dev-v2.5/charts/rancher-logging) + +The `rancher-selinux` GitHub repository is [here.](https://github.com/rancher/rancher-selinux) + +# rke2-selinux + +rke2-selinux provides policies for RKE2. It is installed automatically when the RKE2 installer script detects that it is running on an RPM-based distro. + +The `rke2-selinux` GitHub repository is [here.](https://github.com/rancher/rke2-selinux) + +For more information about installing RKE2 on SELinux-enabled hosts, see the [RKE2 documentation.](https://docs.rke2.io/install/methods/#rpm) + +# Installing the rancher-selinux RPM + +> **Requirements:** The rancher-selinux RPM was tested with CentOS 7 and 8. + +### 1. Set up the yum repo + +Set up the yum repo to install `rancher-selinux` directly on all hosts in the cluster. + +In order to use the RPM repository, on a CentOS 7 or RHEL 7 system, run the following bash snippet: + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` + +In order to use the RPM repository, on a CentOS 8 or RHEL 8 system, run the following bash snippet: + +``` +# cat << EOF > /etc/yum.repos.d/rancher.repo +[rancher] +name=Rancher +baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch +enabled=1 +gpgcheck=1 +gpgkey=https://rpm.rancher.io/public.key +EOF +``` +### 2. Installing the RPM + +Install the RPM: + +``` +yum -y install rancher-selinux +``` + +# Configuring the Logging Application to Work with SELinux + +> **Requirements:** Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8. + +Applications do not automatically work once the `rancher-selinux` RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM. + +To configure the `rancher-logging` chart to be SELinux aware, change `global.seLinux.enabled` to true in the `values.yaml` when installing the chart. diff --git a/content/rancher/v2.x/en/_index.md b/content/rancher/v2.x/en/_index.md index 05241a58db7..1e324546d82 100644 --- a/content/rancher/v2.x/en/_index.md +++ b/content/rancher/v2.x/en/_index.md @@ -1,6 +1,6 @@ --- -title: "Rancher 2.x" -shortTitle: "Rancher 2.x (Archive)" +title: "Rancher 2.0-2.5.6 (Formerly 2.x)" +shortTitle: "Rancher 2.5.6 (Archive)" description: "Rancher adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more." metaTitle: "Rancher 2.x Docs: What is New?" metaDescription: "Rancher 2 adds significant value on top of Kubernetes: managing hundreds of clusters from one interface, centralizing RBAC, enabling monitoring and alerting. Read more." @@ -9,7 +9,9 @@ weight: 1 ctaBanner: 0 --- -> We are transitioning to versioned documentation. The Rancher v2.5 docs are [here.]({{}}/rancher/v2.5/en/) The Rancher v2.0-v2.4 docs are [here.]({{}}/rancher/v2.0-v2.4/en/) The 2.x section contains information for versions v2.0-2.5.6. The v2.x section is still on the Rancher website so that search results won't return 404 errors, but it will no longer be maintained after v2.5.6. +> We are transitioning to versioned documentation. The Rancher v2.5 docs are [here.]({{}}/rancher/v2.5/en/) The Rancher v2.0-v2.4 docs are [here.]({{}}/rancher/v2.0-v2.4/en/) We recommend using the versioned docs because they are easier to read and navigate. +> +> This section, also called 2.x, contains information for versions v2.0-2.5.6. This section is still on the Rancher website so that search results won't return 404 errors, but it will no longer be maintained. Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2.x exclusively deploys and manages Kubernetes clusters running anywhere, on any provider. diff --git a/content/rke/latest/en/config-options/add-ons/_index.md b/content/rke/latest/en/config-options/add-ons/_index.md index a24a6b2d72a..31c819d4b00 100644 --- a/content/rke/latest/en/config-options/add-ons/_index.md +++ b/content/rke/latest/en/config-options/add-ons/_index.md @@ -18,7 +18,12 @@ There are a few things worth noting: * As of v0.1.8, RKE will update an add-on if it is the same name. * Before v0.1.8, update any add-ons by using `kubectl edit`. -## Critical and Non-Critical Add-ons +- [Critical and Non-Critical Add-ons](#critical-and-non-critical-add-ons) +- [Add-on Deployment Jobs](#add-on-deployment-jobs) +- [Add-on Placement](#add-on-placement) +- [Tolerations](#tolerations) + +# Critical and Non-Critical Add-ons As of version v0.1.7, add-ons are split into two categories: @@ -27,7 +32,7 @@ As of version v0.1.7, add-ons are split into two categories: Currently, only the [network plug-in]({{}}/rke/latest/en/config-options/add-ons/network-plugins/) is considered critical. KubeDNS, [ingress controllers]({{}}/rke/latest/en/config-options/add-ons/ingress-controllers/) and [user-defined add-ons]({{}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) are considered non-critical. -## Add-on deployment jobs +# Add-on Deployment Jobs RKE uses Kubernetes jobs to deploy add-ons. In some cases, add-ons deployment takes longer than expected. As of with version v0.1.7, RKE provides an option to control the job check timeout in seconds. This timeout is set at the cluster level. @@ -35,7 +40,7 @@ RKE uses Kubernetes jobs to deploy add-ons. In some cases, add-ons deployment ta addon_job_timeout: 30 ``` -## Add-on placement +# Add-on Placement _Applies to v0.2.3 and higher_ @@ -50,7 +55,7 @@ _Applies to v0.2.3 and higher_ | nginx-ingress | - `beta.kubernetes.io/os:NotIn:windows`
- `node-role.kubernetes.io/worker` `Exists` | none | - `NoSchedule:Exists`
- `NoExecute:Exists` | | metrics-server | - `beta.kubernetes.io/os:NotIn:windows`
- `node-role.kubernetes.io/worker` `Exists` | none | - `NoSchedule:Exists`
- `NoExecute:Exists` | -## Tolerations +# Tolerations _Available as of v1.2.4_ diff --git a/content/rke/latest/en/config-options/add-ons/dns/_index.md b/content/rke/latest/en/config-options/add-ons/dns/_index.md index 1904441038e..2c379980363 100644 --- a/content/rke/latest/en/config-options/add-ons/dns/_index.md +++ b/content/rke/latest/en/config-options/add-ons/dns/_index.md @@ -3,6 +3,25 @@ title: DNS providers weight: 262 --- +- [Available DNS Providers](#available-dns-providers) +- [Disabling deployment of a DNS Provider](#disabling-deployment-of-a-dns-provider) +- [CoreDNS](#coredns) + - [Scheduling CoreDNS](#scheduling-coredns) + - [Upstream nameservers](#coredns-upstream-nameservers) + - [Priority Class Name](#coredns-priority-class-name) + - [Tolerations](#coredns-tolerations) +- [kube-dns](#kube-dns) + - [Scheduling kube-dns](#scheduling-kube-dns) + - [Upstream nameservers](#kube-dns-upstream-nameservers) + - [Priority Class Name](#kube-dns-priority-class-name) + - [Tolerations](#kube-dns-tolerations) +- [NodeLocal DNS](#nodelocal-dns) + - [Configuring NodeLocal DNS](#configuring-nodelocal-dns) + - [Priority Class Name](#nodelocal-priority-class-name) + - [Removing NodeLocal DNS](#removing-nodelocal-dns) + +# Available DNS Providers + RKE provides the following DNS providers that can be deployed as add-ons: * [CoreDNS](https://coredns.io) @@ -18,6 +37,17 @@ CoreDNS was made the default in RKE v0.2.5 when using Kubernetes 1.14 and higher > **Note:** If you switch from one DNS provider to another, the existing DNS provider will be removed before the new one is deployed. +# Disabling Deployment of a DNS Provider + +_Available as of v0.2.0_ + +You can disable the default DNS provider by specifying `none` to the dns `provider` directive in the cluster configuration. Be aware that this will prevent your pods from doing name resolution in your cluster. + +```yaml +dns: + provider: none +``` + # CoreDNS _Available as of v0.2.5_ @@ -28,7 +58,7 @@ RKE will deploy CoreDNS as a Deployment with the default replica count of 1. The The images used for CoreDNS are under the [`system_images` directive]({{}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with CoreDNS, but these can be overridden by changing the image tag in `system_images`. -## Scheduling CoreDNS +### Scheduling CoreDNS If you only want the CoreDNS pod to be deployed on specific nodes, you can set a `node_selector` in the `dns` section. The label in the `node_selector` would need to match the label on the nodes for the CoreDNS pod to be deployed. @@ -46,9 +76,8 @@ dns: app: dns ``` -## Configuring CoreDNS -### Upstream nameservers +### CoreDNS Upstream nameservers By default, CoreDNS will use the host configured nameservers (usually residing at `/etc/resolv.conf`) to resolve external queries. If you want to configure specific upstream nameservers to be used by CoreDNS, you can use the `upstreamnameservers` directive. @@ -62,13 +91,28 @@ dns: - 8.8.4.4 ``` -### Tolerations + +### CoreDNS Priority Class Name + +_Available as of RKE v1.2.6+_ + +The [pod priority](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#pod-priority) is set by configuring a priority class name under `options`: + +```yaml +dns: + options: + coredns_autoscaler_priority_class_name: system-cluster-critical + coredns_priority_class_name: system-cluster-critical + provider: coredns +``` + +### CoreDNS Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `coredns` and the `coredns-autoscaler` Deployment. -``` +```yaml dns: provider: coredns tolerations: @@ -95,7 +139,7 @@ RKE will deploy kube-dns as a Deployment with the default replica count of 1. Th The images used for kube-dns are under the [`system_images` directive]({{}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with kube-dns, but these can be overridden by changing the image tag in `system_images`. -## Scheduling kube-dns +### Scheduling kube-dns _Available as of v0.2.0_ @@ -115,9 +159,7 @@ dns: app: dns ``` -## Configuring kube-dns - -### Upstream nameservers +### kube-dns Upstream nameservers _Available as of v0.2.0_ @@ -133,13 +175,28 @@ dns: - 8.8.4.4 ``` -### Tolerations +### kube-dns Priority Class Name + +_Available as of RKE v1.2.6+_ + +The [pod priority](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#pod-priority) is set by configuring a priority class name under `options`: + +```yaml +dns: + options: + kube_dns_autoscaler_priority_class_name: system-cluster-critical + kube_dns_priority_class_name: system-cluster-critical + provider: kube-dns +``` + + +### kube-dns Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `kube-dns` and the `kube-dns-autoscaler` Deployment. -``` +```yaml dns: provider: kube-dns tolerations: @@ -161,16 +218,7 @@ kubectl get deploy kube-dns -n kube-system -o jsonpath='{.spec.template.spec.tol kubectl get deploy kube-dns-autoscaler -n kube-system -o jsonpath='{.spec.template.spec.tolerations}' ``` -# Disabling deployment of a DNS provider -_Available as of v0.2.0_ - -You can disable the default DNS provider by specifying `none` to the dns `provider` directive in the cluster configuration. Be aware that this will prevent your pods from doing name resolution in your cluster. - -```yaml -dns: - provider: none -``` # NodeLocal DNS @@ -186,7 +234,7 @@ NodeLocal DNS is an additional component that can be deployed on each node to im Enable NodeLocal DNS by configuring an IP address. -## Configuring NodeLocal DNS +### Configuring NodeLocal DNS The `ip_address` parameter is used to configure what link-local IP address will be configured one each host to listen on, make sure this IP address is not already configured on the host. @@ -199,7 +247,21 @@ dns: > **Note:** When enabling NodeLocal DNS on an existing cluster, pods that are currently running will not be modified, the updated `/etc/resolv.conf` configuration will take effect only for pods started after enabling NodeLocal DNS. -## Removing NodeLocal DNS +### NodeLocal Priority Class Name + +_Available as of RKE v1.2.6+_ + +The [pod priority](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#pod-priority) is set by configuring a priority class name under `options`: + +```yaml +dns: + options: + nodelocal_autoscaler_priority_class_name: system-cluster-critical + nodelocal_priority_class_name: system-cluster-critical + provider: coredns # a DNS provider must be configured +``` + +### Removing NodeLocal DNS By removing the `ip_address` value, NodeLocal DNS will be removed from the cluster. diff --git a/content/rke/latest/en/config-options/add-ons/ingress-controllers/_index.md b/content/rke/latest/en/config-options/add-ons/ingress-controllers/_index.md index 62d29580145..827046e6f61 100644 --- a/content/rke/latest/en/config-options/add-ons/ingress-controllers/_index.md +++ b/content/rke/latest/en/config-options/add-ons/ingress-controllers/_index.md @@ -4,6 +4,17 @@ description: By default, RKE deploys the NGINX ingress controller. Learn how to weight: 262 --- +- [Default Ingress](#default-ingress) +- [Scheduling Ingress Controllers](#scheduling-ingress-controllers) +- [Ingress Priority Class Name](#ingress-priority-class-name) +- [Tolerations](#tolerations) +- [Disabling the Default Ingress Controller](#disabling-the-default-ingress-controller) +- [Configuring NGINX Ingress Controller](#configuring-nginx-ingress-controller) +- [Disabling NGINX Ingress Default Backend](#disabling-nginx-ingress-default-backend) +- [Configuring an NGINX Default Certificate](#configuring-an-nginx-default-certificate) + +### Default Ingress + By default, RKE deploys the NGINX ingress controller on all schedulable nodes. > **Note:** As of v0.1.8, only workers are considered schedulable nodes, but before v0.1.8, worker and controlplane nodes were considered schedulable nodes. @@ -12,7 +23,7 @@ RKE will deploy the ingress controller as a DaemonSet with `hostnetwork: true`, The images used for ingress controller is under the [`system_images` directive]({{}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with the ingress controller, but these can be overridden by changing the image tag in `system_images`. -## Scheduling Ingress Controllers +### Scheduling Ingress Controllers If you only wanted ingress controllers to be deployed on specific nodes, you can set a `node_selector` for the ingress. The label in the `node_selector` would need to match the label on the nodes for the ingress controller to be deployed. @@ -30,13 +41,25 @@ ingress: app: ingress ``` -## Tolerations +### Ingress Priority Class Name + +_Available as of RKE v1.2.6+_ + +The [pod priority](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#pod-priority) is set by configuring a priority class name: + +```yaml +ingress: + provider: nginx + ingress_priority_class_name: system-cluster-critical +``` + +### Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `default-http-backend` Deployment. -``` +```yaml ingress: tolerations: - key: "node.kubernetes.io/unreachable" @@ -55,7 +78,7 @@ To check for applied tolerations `default-http-backend` Deployment, use the foll kubectl -n ingress-nginx get deploy default-http-backend -o jsonpath='{.spec.template.spec.tolerations}' ``` -## Disabling the Default Ingress Controller +### Disabling the Default Ingress Controller You can disable the default controller by specifying `none` to the ingress `provider` directive in the cluster configuration. @@ -63,7 +86,7 @@ You can disable the default controller by specifying `none` to the ingress `pro ingress: provider: none ``` -## Configuring NGINX Ingress Controller +### Configuring NGINX Ingress Controller For the configuration of NGINX, there are configuration options available in Kubernetes. There are a [list of options for the NGINX config map](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md) , [command line extra_args](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/cli-arguments.md) and [annotations](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/). @@ -88,7 +111,7 @@ ingress: > **What happens if the field is omitted?** The value of `default_backend` will default to `true`. This maintains behavior with older versions of `rke`. However, a future version of `rke` will change the default value to `false`. -## Configuring an NGINX Default Certificate +### Configuring an NGINX Default Certificate When configuring an ingress object with TLS termination, you must provide it with a certificate used for encryption/decryption. Instead of explicitly defining a certificate each time you configure an ingress, you can set up a custom certificate that's used by default. diff --git a/content/rke/latest/en/config-options/add-ons/metrics-server/_index.md b/content/rke/latest/en/config-options/add-ons/metrics-server/_index.md index 21c541dc344..0171477036b 100644 --- a/content/rke/latest/en/config-options/add-ons/metrics-server/_index.md +++ b/content/rke/latest/en/config-options/add-ons/metrics-server/_index.md @@ -9,13 +9,17 @@ RKE will deploy Metrics Server as a Deployment. The image used for Metrics Server is under the [`system_images` directive]({{}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there is a default image associated with the Metrics Server, but these can be overridden by changing the image tag in `system_images`. -## Tolerations +- [Tolerations](#tolerations) +- [Priority Class Name](#metrics-server-priority-class-name) +- [Disabling the Metrics Server](#disabling-the-metrics-server) + +### Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `metrics-server` Deployment. -``` +```yaml monitoring: tolerations: - key: "node.kubernetes.io/unreachable" @@ -34,7 +38,19 @@ To check for applied tolerations on the `metrics-server` Deployment, use the fol kubectl -n kube-system get deploy metrics-server -o jsonpath='{.spec.template.spec.tolerations}' ``` -## Disabling the Metrics Server +### Metrics Server Priority Class Name + +_Available as of RKE v1.2.6+_ + +The [pod priority](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#pod-priority) is set by configuring a priority class name: + +```yaml +monitoring: + provider: metrics-server + metrics_server_priority_class_name: system-cluster-critical +``` + +### Disabling the Metrics Server _Available as of v0.2.0_ diff --git a/content/rke/latest/en/config-options/add-ons/network-plugins/_index.md b/content/rke/latest/en/config-options/add-ons/network-plugins/_index.md index 88828943652..1648aac99c2 100644 --- a/content/rke/latest/en/config-options/add-ons/network-plugins/_index.md +++ b/content/rke/latest/en/config-options/add-ons/network-plugins/_index.md @@ -10,7 +10,27 @@ RKE provides the following network plug-ins that are deployed as add-ons: - Canal - Weave -> **Note:** After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn’t allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications. +> After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn’t allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications. + +- [Changing the Default Network Plug-in](#changing-the-default-network-plug-in) +- [Disabling Deployment of a Network Plug-in](#disabling-deployment-of-a-network-plug-in) +- [Network Plug-in Options](#network-plug-in-options) +- [Canal](#canal) + - [Canal Network Plug-in Options](#canal-network-plug-in-options) + - [Canal Interface](#canal-interface) + - [Canal Network Plug-in Tolerations](#canal-network-plug-in-tolerations) +- [Flannel](#flannel) + - [Flannel Network Plug-in Options](#flannel-network-plug-in-options) + - [Flannel Interface](#flannel-interface) +- [Calico](#calico) + - [Calico Network Plug-in Options](#calico-network-plug-in-options) + - [Calico Cloud Provider](#calico-cloud-provider) + - [Calico Network Plug-in Tolerations](#calico-network-plug-in-tolerations) +- [Weave](#weave) + - [Weave Network Plug-in Options](#weave-network-plug-in-options) +- [Custom Network Plug-ins](#custom-network-plug-ins) + +# Changing the Default Network Plug-in By default, the network plug-in is `canal`. If you want to use another network plug-in, you need to specify which network plug-in to enable at the cluster level in the `cluster.yml`. @@ -35,7 +55,14 @@ network: Besides the different images that could be used to deploy network plug-ins, certain network plug-ins support additional options that can be used to customize the network plug-in. -## Canal Network Plug-in Options +- [Canal](#canal) +- [Flannel](#flannel) +- [Calico](#calico) +- [Weave](#weave) + +# Canal + +### Canal Network Plug-in Options ```yaml network: @@ -43,20 +70,23 @@ network: options: canal_iface: eth1 canal_flannel_backend_type: vxlan + canal_autoscaler_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ + canal_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ ``` -#### Canal Interface +### Canal Interface By setting the `canal_iface`, you can configure the interface to use for inter-host communication. + The `canal_flannel_backend_type` option allows you to specify the type of [flannel backend](https://github.com/coreos/flannel/blob/master/Documentation/backends.md) to use. By default the `vxlan` backend is used. -## Canal Network Plug-in Tolerations +### Canal Network Plug-in Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `calico-kube-controllers` Deployment. -``` +```yaml network: plugin: canal tolerations: @@ -76,7 +106,8 @@ To check for applied tolerations on the `calico-kube-controllers` Deployment, us kubectl -n kube-system get deploy calico-kube-controllers -o jsonpath='{.spec.template.spec.tolerations}' ``` -## Flannel Network Plug-in Options +# Flannel +### Flannel Network Plug-in Options ```yaml network: @@ -84,22 +115,29 @@ network: options: flannel_iface: eth1 flannel_backend_type: vxlan + flannel_autoscaler_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ + flannel_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ ``` -#### Flannel Interface +### Flannel Interface By setting the `flannel_iface`, you can configure the interface to use for inter-host communication. The `flannel_backend_type` option allows you to specify the type of [flannel backend](https://github.com/coreos/flannel/blob/master/Documentation/backends.md) to use. By default the `vxlan` backend is used. -## Calico Network Plug-in Options + +# Calico + +### Calico Network Plug-in Options ```yaml network: plugin: calico options: calico_cloud_provider: aws + calico_autoscaler_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ + calico_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ ``` -#### Calico Cloud Provider +### Calico Cloud Provider Calico currently only supports 2 cloud providers, AWS or GCE, which can be set using `calico_cloud_provider`. @@ -108,13 +146,13 @@ Calico currently only supports 2 cloud providers, AWS or GCE, which can be set u - `aws` - `gce` -## Calico Network Plug-in Tolerations +### Calico Network Plug-in Tolerations _Available as of v1.2.4_ The configured tolerations apply to the `calico-kube-controllers` Deployment. -``` +```yaml network: plugin: calico tolerations: @@ -134,19 +172,23 @@ To check for applied tolerations on the `calico-kube-controllers` Deployment, us kubectl -n kube-system get deploy calico-kube-controllers -o jsonpath='{.spec.template.spec.tolerations}' ``` -## Weave Network Plug-in Options +# Weave +### Weave Network Plug-in Options ```yaml network: plugin: weave + options: + weave_autoscaler_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ + weave_priority_class_name: system-cluster-critical # Available as of RKE v1.2.6+ weave_network_provider: password: "Q]SZOQ5wp@n$oijz" ``` -#### Weave encryption +### Weave Encryption Weave encryption can be enabled by passing a string password to the network provider config. -## Custom Network Plug-ins +# Custom Network Plug-ins It is possible to add a custom network plug-in by using the [user-defined add-on functionality]({{}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) of RKE. In the `addons` field, you can add the add-on manifest of a cluster that has the network plugin-that you want, as shown in [this example.]({{}}/rke/latest/en/config-options/add-ons/network-plugins/custom-network-plugin-example)