diff --git a/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md b/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md index d7eb5fa7dd5..df0a8c1aeb8 100644 --- a/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md @@ -12,13 +12,13 @@ After you provision a Kubernetes cluster using Rancher, you can still edit optio The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters [provisioned by RKE]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) have **Cluster Options** available for editing. -The following table lists the options and settings available for each cluster type: +The following table summarizes the options and settings available for each cluster type: - Cluster Type | Member Roles | Cluster Options | Node Pools ----------|----------|---------|---------| - [RKE-Launched]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#rancher-launched-kubernetes) | ✓ | ✓ | ✓ | - [Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#hosted-kubernetes-cluster) | ✓ | | | - [Imported]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) | ✓ | | | + Rancher Capability | RKE Launched | Hosted Kubernetes Cluster | Imported Cluster + ---------|----------|---------|---------| + Manage member roles | ✓ | ✓ | ✓ + Edit cluster options | ✓ | | + Manage node pools | ✓ | | ## Editing Cluster Membership @@ -62,11 +62,13 @@ Option | Description | >**Note:** In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: `kube_api` and `kube_controller`. -Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{< baseurl >}}/rke/latest/en/config-options/) in an RKE installation. +Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML. - To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**. - To read from an existing RKE file, click **Read from File**. +In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. For more information, see the section about the [cluster config file.](#cluster-config-file) + ![image]({{< baseurl >}}/img/rancher/cluster-options-yaml.png) For an example of RKE config file syntax, see the [RKE documentation]({{< baseurl >}}/rke/latest/en/example-yamls/). diff --git a/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/attaching-existing-storage/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/attaching-existing-storage/_index.md index 6ecdc1050e2..9a295113bca 100644 --- a/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/attaching-existing-storage/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/attaching-existing-storage/_index.md @@ -18,7 +18,7 @@ To set up storage, follow these steps: - Rancher can only dynamically provision new storage in clusters [created with RKE.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) - To create a persistent volume as a Kubernetes resource, you must have the `Manage Volumes` [role.]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) -- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider, and the cloud provider must be enabled. The cloud provider must be enabled when the cluster is provisioned. For details on enabling cloud providers, refer to [this page.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) +- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider, and the cloud provider must be enabled. For details on enabling cloud providers, refer to [this page.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) ### 1. Set up persistent storage in an infrastructure provider diff --git a/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/provisioning-new-storage/_index.md b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/provisioning-new-storage/_index.md index bb9e42af2a1..17cb92db370 100644 --- a/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/provisioning-new-storage/_index.md +++ b/content/rancher/v2.x/en/cluster-admin/volumes-and-storage/provisioning-new-storage/_index.md @@ -17,7 +17,7 @@ To provision new storage for your workloads, follow these steps: - Rancher can only dynamically provision new storage in clusters [created with RKE.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) - To set up persistent storage, the `Manage Volumes` [role]({{}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) is required. -- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider, and the cloud provider must be enabled. The cloud provider must be enabled when the cluster is provisioned. For details on enabling cloud providers, refer to [this page.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) +- If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider, and the cloud provider must be enabled. For details on enabling cloud providers, refer to [this page.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) - Make sure your storage provisioner is available to be enabled. The following storage provisioners are enabled by default: diff --git a/content/rancher/v2.x/en/cluster-provisioning/_index.md b/content/rancher/v2.x/en/cluster-provisioning/_index.md index 778123a3c45..5c07267cae6 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/_index.md @@ -1,5 +1,5 @@ --- -title: Provisioning Kubernetes Clusters +title: Setting up Kubernetes Clusters in Rancher description: Provisioning Kubernetes Clusters weight: 2000 aliases: @@ -15,29 +15,35 @@ This section assumes a basic familiarity with Docker and Kubernetes. For a brief For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) page. -## Cluster Creation Options - -Options include: +This section covers the following topics: - -- [Hosted Kubernetes Cluster](#hosted-kubernetes-cluster) -- [Rancher Launched Kubernetes](#rancher-launched-kubernetes) - - [Nodes Hosted by an Infrastructure Provider](#nodes-hosted-by-an-infrastructure-provider) - - [Custom Nodes](#custom-nodes) -- [Import Existing Cluster](#import-existing-cluster) - +- [Setting up clusters in a hosted Kubernetes provider](#setting-up-clusters-in-a-hosted-kubernetes-cluster) +- [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) + - [Launching Kubernetes on Existing Custom Nodes](#launching-kubernetes-on-existing-custom-nodes) +- [Importing Existing Cluster](#importing-existing-cluster) -# Hosted Kubernetes Cluster +The following table summarizes the options and settings available for each cluster type: -If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage a hosted cluster from the Rancher UI. + Rancher Capability | RKE Launched | Hosted Kubernetes Cluster | Imported Cluster + ---------|----------|---------|---------| + Manage member roles | ✓ | ✓ | ✓ + Edit cluster options | ✓ | | + Manage node pools | ✓ | | -[Hosted Kubernetes Cluster]({{}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) +# Setting up Clusters in a Hosted Kubernetes Provider -# Rancher Launched Kubernetes +In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. -The [Rancher Kubernetes Engine (RKE)]({{}}/rke/latest/en/) allows you to create a Kubernetes cluster on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer. +If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI. + +For more information, refer to the section on [hosted Kubernetes clusters.]({{}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) + +# Launching Kubernetes with Rancher + +Rancher uses the [Rancher Kubernetes Engine (RKE)]({{}}/rke/latest/en/)as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer. In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform. @@ -47,27 +53,29 @@ If you already have a node that you want to add to an RKE cluster, you can add i For more information, refer to the section on [RKE clusters.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) -### Nodes Hosted by an Infrastructure Provider +### Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider + +Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them. Using Rancher, you can create pools of nodes based on a [node template]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This template defines the parameters used to launch nodes in your cloud providers. -The benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher automatically replaces it, thus maintaining the expected cluster configuration. +One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration. The cloud providers available for creating a node template are decided based on the [node drivers]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers) active in the Rancher UI. For more information, refer to the section on [nodes hosted by an infrastructure provider]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) -### Custom Nodes +### Launching Kubernetes on Existing Custom Nodes -You can bring any nodes you want to Rancher and use them to create a cluster. Clusters created with custom nodes are also called custom clusters. +When setting up this type of cluster, Rancher installs Kubernetes on existing [custom nodes,]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) which creates a custom cluster. + +You can bring any nodes you want to Rancher and use them to create a cluster. These nodes include on-premise bare metal servers, cloud-hosted virtual machines, or on-premise virtual machines. -[Custom Nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) +# Importing Existing Clusters -# Import Existing Cluster - -Users can import an existing Kubernetes cluster into Rancher. +In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. All other Rancher features, including management of cluster, policy, and workloads, are available for imported clusters. diff --git a/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md deleted file mode 100644 index 8c9cb4a8504..00000000000 --- a/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Custom Cluster -weight: 2210 ---- - -When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to provision the Kubernetes cluster on your existing infrastructure. - -If you don't want to host your Kubernetes cluster in a [hosted kubernetes provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters) or provision nodes through Rancher, you can use the _custom cluster_ option to create a Kubernetes cluster in on-premise bare-metal servers, on-premise virtual machines, or in _any_ node hosted by an infrastructure provider. - -In this scenario, you'll bring the nodes yourself, and then configure them to meet Rancher's [requirements]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/#requirements). Then, use the [Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) install option to set up your cluster. diff --git a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md index 69f0250ac1f..8a5fc2495de 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/_index.md @@ -1,11 +1,13 @@ --- -title: Hosted Kubernetes Providers +title: Setting up Clusters from Hosted Kubernetes Providers weight: 2100 --- -You can use Rancher to create clusters in a hosted Kubernetes provider, such as Google GKE. +In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service. -In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-premise or in an infrastructure provider, all from the same UI. +If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI. + +In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-premise or in an infrastructure provider. Rancher supports the following Kubernetes providers: diff --git a/content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md index e5172a8af7e..e1cf1478588 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/imported-clusters/_index.md @@ -1,5 +1,5 @@ --- -title: Import an Existing Cluster to Create a Cluster in Rancher +title: Importing Existing Clusters into Rancher description: Learn how you can create a cluster in Rancher by importing an existing Kubernetes cluster. Then, you can manage it using Rancher metaTitle: "Kubernetes Cluster Management" metaDescription: "Learn how you can import an existing Kubernetes cluster and then manage it using Rancher" @@ -8,31 +8,36 @@ aliases: - /rancher/v2.x/en/tasks/clusters/import-cluster/ --- -You can import an existing Kubernetes cluster and then manage it using Rancher. Keep in mind that editing your Kubernetes cluster (for example: adding/removing nodes, upgrading Kubernetes cluster version and changing Kubernetes component parameters) still has to be done outside of Rancher. +When managing an imported cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster. ->**Prerequisites:** -> ->- If your existing Kubernetes cluster already has a `cluster-admin` role defined, you must have this `cluster-admin` privilege to import the cluster into Rancher. In order to apply the privilege, you need to run `kubectl create clusterrolebinding cluster-admin-binding --clusterrole cluster-admin --user [USER_ACCOUNT]` before running the `kubectl` command to import the cluster. ->- By default, GKE users are not given this privilege, so you will need to run the command before importing GKE clusters. To learn more about GKE RBAC, please click [here](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control). +Keep in mind that editing your Kubernetes cluster still has to be done outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters. + +### Prerequisites + +If your existing Kubernetes cluster already has a `cluster-admin` role defined, you must have this `cluster-admin` privilege to import the cluster into Rancher. + +In order to apply the privilege, you need to run: + +```plain +kubectl create clusterrolebinding cluster-admin-binding \ + --clusterrole cluster-admin \ + --user [USER_ACCOUNT] +``` +before running the `kubectl` command to import the cluster. + +By default, GKE users are not given this privilege, so you will need to run the command before importing GKE clusters. To learn more about role-based access control for GKE, please click [here](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control). + +### Importing a Cluster 1. From the **Clusters** page, click **Add Cluster**. - 2. Choose **Import**. - 3. Enter a **Cluster Name**. - 4. {{< step_create-cluster_member-roles >}} - 5. Click **Create**. - 6. The prerequisite for `cluster-admin` privileges is shown (see **Prerequisites** above), including an example command to fulfil the prerequisite. - 7. Copy the `kubectl` command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run `kubectl get nodes` to verify before running the command shown in {{< product >}}. - 8. If you are using self signed certificates, you will receive the message `certificate signed by unknown authority`. To work around this validation, copy the command starting with `curl` displayed in {{< product >}} to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import. - 9. When you finish running the command(s) on your node, click **Done**. - {{< result_import-cluster >}} > **Note:** diff --git a/content/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles/_index.md b/content/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles/_index.md index 59a68d37a81..da12ee46111 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles/_index.md @@ -5,7 +5,7 @@ weight: 1 This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster. -This diagram is applicable to Kubernetes clusters built using RKE or [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). +This diagram is applicable to Kubernetes clusters [launched with Rancher using RKE.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). ![Cluster diagram]({{< baseurl >}}/img/rancher/clusterdiagram.svg)
Lines show the traffic flow between components. Colors are used purely for visual aid diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md index 417cdf3c295..781d9d9948b 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/_index.md @@ -1,32 +1,32 @@ --- -title: Rancher Launched Kubernetes +title: Launching Kubernetes with Rancher weight: 2200 --- -If you don't want to use a hosted Kubernetes provider, you can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses [Rancher Kubernetes Engine]({{< baseurl >}}/rke/latest/en/) (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including: +You can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses [Rancher Kubernetes Engine]({{}}/rke/latest/en/) (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including: - Bare-metal servers - On-premise virtual machines - Virtual machines hosted by an infrastructure provider -RKE launched clusters are separated into two categories: - -- [Nodes Hosted by an Infrastructure Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/): - - Using Rancher, you can create pools of nodes based on a [node template]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your cloud providers. The available cloud providers to create a node template are decided based on active [node drivers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers). The benefit of using a node hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher will automatically create another node to join the cluster to ensure that the count of the node pool is as expected. - - As of v2.2.0, [cloud credential]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#cloud-credentials) are created to store credentials for launching nodes in your infrastructure providers. There are two benefits of using a cloud credential: - - Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time. - - Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once. - -- [Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/): - - For use cases where you want to provision bare-metal servers, on-premise virtual machines, or bring virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine. - - >**Note:** If you want to reuse a node from a previous custom cluster, [clean the node]({{< baseurl >}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. - -
+Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them. ### Requirements -If you use RKE to set up a cluster, your cluster nodes must meet our [Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements). +If you use RKE to set up a cluster, your nodes must meet the [requirements]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements) for nodes in downstream user clusters. + +### Launching Kubernetes on New Nodes in an Infrastructure Provider + +Using Rancher, you can create pools of nodes based on a [node template]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your cloud providers. + +One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +For more information, refer to the section on [launching Kubernetes on new nodes.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) + +### Launching Kubernetes on Existing Custom Nodes + +In this scenario, you want to install Kubernetes on bare-metal servers, on-premise virtual machines, or virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine. + +If you want to reuse a node from a previous custom cluster, [clean the node]({{}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. + +For more information, refer to the section on [custom nodes.]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md index 3ba53e83e2d..db7102d5bf9 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/_index.md @@ -1,24 +1,24 @@ --- -title: Creating a Cluster with Custom Nodes +title: Launching Kubernetes on Existing Custom Nodes description: To create a cluster with custom nodes, you’ll need to access servers in your cluster and provision them according to Rancher requirements metaDescription: "To create a cluster with custom nodes, you’ll need to access servers in your cluster and provision them according to Rancher requirements" -shortTitle: Custom Nodes weight: 2225 aliases: - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-custom/ + - /rancher/v2.x/en/cluster-provisioning/custom-clusters --- -When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to provision the Kubernetes cluster on your existing infrastructure. This section describes how to set up a custom cluster. +When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to create a Kubernetes cluster in on-premise bare-metal servers, on-premise virtual machines, or in any node hosted by an infrastructure provider. -## Custom Nodes +To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to the [requirements]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements), which includes some hardware specifications and Docker. After you install Docker on each server, run the command provided in the Rancher UI to turn each server into a Kubernetes node. -To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to Rancher [requirements](#requirements), which includes some hardware specifications and Docker. After you install Docker on each server, run the command provided in the Rancher UI to turn each server into a Kubernetes node. +This section describes how to set up a custom cluster. -## Objectives for Creating Cluster with Custom Nodes +# Creating a Cluster with Custom Nodes >**Want to use Windows hosts as Kubernetes workers?** > ->See [Configuring Custom Clusters for Windows]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/) before you start. +>See [Configuring Custom Clusters for Windows]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/) before you start. @@ -28,7 +28,7 @@ To use this option you'll need access to servers you intend to use in your Kuber -## 1. Provision a Linux Host +### 1. Provision a Linux Host Begin creation of a custom cluster by provisioning a Linux host. Your host can be: @@ -36,18 +36,11 @@ Begin creation of a custom cluster by provisioning a Linux host. Your host can b - An on-premise VM - A bare-metal server ->**Notes:** -> ->- While creating your cluster, you must assign Kubernetes roles to your cluster nodes. If you plan on dedicating servers to each role, you must provision a server for each role (i.e. provision multiple servers). ->- If you want to reuse a node from a previous custom cluster, [clean the node]({{< baseurl >}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. +If you want to reuse a node from a previous custom cluster, [clean the node]({{}}/rancher/v2.x/en/admin-settings/removing-rancher/rancher-cluster-nodes/) before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail. -Provision the host according to the requirements below. +Provision the host according to the [installation requirements]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements) and the [checklist for production-ready clusters.]({{}}/rancher/v2.x/en/cluster-provisioning/production) -### Requirements - -Each node in your cluster must meet our [Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements). - -## 2. Create the Custom Cluster +### 2. Create the Custom Cluster 1. From the **Clusters** page, click **Add Cluster**. @@ -84,7 +77,7 @@ Each node in your cluster must meet our [Requirements]({{< baseurl >}}/rancher/v {{< result_create-cluster >}} -## 3. Amazon Only: Tag Resources +### 3. Amazon Only: Tag Resources If you have configured your cluster to use Amazon as **Cloud Provider**, tag your AWS resources with a cluster ID. diff --git a/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/agent-options/_index.md similarity index 87% rename from content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/agent-options/_index.md index 72156f1e8e9..58fc18c181d 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/agent-options/_index.md @@ -1,12 +1,15 @@ --- title: Rancher Agent Options -weight: 1140 +weight: 2500 aliases: - /rancher/v2.x/en/admin-settings/agent-options/ - + - /rancher/v2.x/en/cluster-provisioning/custom-clusters/agent-options + - /rancher/v2.x/en/cluster-provisioning/rke-clusters/agent-options --- -Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to [Create a Cluster with Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) and add the options to the generated `docker run` command when adding a node. +Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to [create a cluster with custom nodes]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/) and add the options to the generated `docker run` command when adding a node. + +For an overview of how Rancher communicates with downstream clusters using node agents, refer to the [architecture section.]({{}}/rancher/v2.x/en/overview/architecture/#3-node-agents) ## General options diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md index 7fc3ae981df..0d7a0e5ab67 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/_index.md @@ -1,10 +1,29 @@ --- -title: Nodes Hosted in an Infrastructure Provider +title: Launching Kubernetes on New Nodes in an Infrastructure Provider weight: 2205 aliases: - /rancher/v2.x/en/concepts/global-configuration/node-templates/ --- +Using Rancher, you can create pools of nodes based on a [node template]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-templates). This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers. + +One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected. + +The available cloud providers to create a node template are decided based on active [node drivers]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/#node-drivers). + +This section covers the following topics: + +- [Node templates](#node-templates) + - [Node labels](#node-labels) + - [Node taints](#node-taints) +- [Node pools](#node-pools) + - [Node pool taints](#node-pool-taints) + - [About node auto-replace](#about-node-auto-replace) + - [Enabling node auto-replace](#enabling-node-auto-replace) + - [Disabling node auto-replace](#disabling-node-auto-replace) +- [Cloud credentials](#cloud-credentials) +- [Node drivers](#node-drivers) + # Node Templates A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses [Docker Machine](https://docs.docker.com/machine/) to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher. @@ -39,13 +58,13 @@ For each taint, they will automatically be added to any created node in the node When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template. -### Node Auto-replace +### About Node Auto-replace _Available as of Rancher v2.3.0_ If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes. -> **Important** Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. +> **Important:** Self-healing node pools are designed to help you replace worker nodes for **stateless** applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications. {{% accordion id="how-does-node-auto-replace-work" label="How does Node Auto-replace Work?" %}} Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the `--node-monitor-period` flag of the `kube-controller`). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool. @@ -87,11 +106,11 @@ _Available as of v2.2.0_ Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits: -- Cloud credentials are stored as Kubernetes secrets for security. Credentials are no longer needed to be re-entered any time you want to edit a node template. +- Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time. - After the cloud credential is created, it can be re-used to create additional node templates. -- When access and secret keys are expired or compromised, the cloud credential can be updated with the new information, which will automatically be updated for all the node templates referencing this cloud credential. +- Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once. > **Note:** As of v2.2.0, the default `active` [node drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/) and any node driver, that has fields marked as `password`, are required to use cloud credentials. If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it. @@ -99,4 +118,4 @@ After cloud credentials are created, the user can start [managing the cloud cred # Node Drivers -If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#activating-deactivating-node-drivers), or you can [add your own custom node driver]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#adding-custom-node-drivers). +If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in [node drivers and activate it]({{}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#activating-deactivating-node-drivers), or you can [add your own custom node driver]({{}}/rancher/v2.x/en/admin-settings/drivers/node-drivers/#adding-custom-node-drivers). diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md index d1f29074b38..66bd63c7bb7 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/azure/_index.md @@ -24,9 +24,7 @@ Use {{< product >}} to create a Kubernetes cluster in Azure. 2. Complete the **Azure Options** form. - - **Account Access** stores your account information for authenticating with Azure. - - {{< step_create-cloud-credential >}} + - **Account Access** stores your account information for authenticating with Azure. Note: As of v2.2.0, account access information is stored as a cloud credentials. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. To create a new cloud credential, enter **Name** and **Account Access** data, then click **Create.** - **Placement** sets the geographical region where your cluster is hosted and other location metadata. diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md index 811bb6fb8fb..fcb904d9604 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/digital-ocean/_index.md @@ -19,14 +19,12 @@ Use {{< product >}} to create a Kubernetes cluster using DigitalOcean. 6. {{< step_create-cluster_node-pools >}} - 1. Click **Add Node Template**. + 1. Click **Add Node Template**. Note: As of v2.2.0, account access information is stored as a cloud credentials. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. To create a new cloud credential, enter **Name** and **Account Access** data, then click **Create.** 2. Complete the **Digital Ocean Options** form. - **Access Token** stores your DigitalOcean Personal Access Token. Refer to [DigitalOcean Instructions: How To Generate a Personal Access Token](https://www.digitalocean.com/community/tutorials/how-to-use-the-digitalocean-api-v2#how-to-generate-a-personal-access-token). - {{< step_create-cloud-credential >}} - - **Droplet Options** provision your cluster's geographical region and specifications. 4. {{< step_rancher-template >}} diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md index c702095a959..77b1496fbf1 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md @@ -6,19 +6,79 @@ weight: 2210 aliases: - /rancher/v2.x/en/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2/ --- -Use {{< product >}} to create a Kubernetes cluster in Amazon EC2. +Use Rancher to create a Kubernetes cluster in Amazon EC2. -## Prerequisites +### Prerequisites -- AWS EC2 Access Key and Secret key that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. -- IAM Policy created to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below: +- **AWS EC2 Access Key and Secret Key** that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key. +- **IAM Policy created** to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below: - [Example IAM Policy](#example-iam-policy) - [Example IAM Policy with PassRole](#example-iam-policy-with-passrole) (needed if you want to use [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers) or want to pass an IAM Profile to an instance) - [Example IAM Policy to allow encrypted EBS volumes](#example-iam-policy-to-allow-encrypted-ebs-volumes) -- IAM Policy added as Permission to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user. +- **IAM Policy added as Permission** to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user. +# Creating an EC2 Cluster -## Create the cluster +The steps to create a cluster differ based on your Rancher version. + +{{% tabs %}} +{{% tab "Rancher v2.2.0+" %}} + +1. [Create your cloud credentials](#1-create-your-cloud-credentials) +2. [Create a node template with your cloud credentials and information from EC2](#2-create-a-node-template-with-your-cloud-credentials-and-information-from-ec2) +3. [Create a cluster with node pools using the node template](#3-create-a-cluster-with-node-pools-using-the-node-template) + +### 1. Create your cloud credentials + +1. In the Rancher UI, click the user profile button in the upper right corner, and click **Cloud Credentials.** +1. Click **Add Cloud Credential.** +1. Enter a name for the cloud credential. +1. In the **Cloud Credential Type** field, select **Amazon.** +1. In the **Region** field, select the AWS region where your cluster nodes will be located. +1. Enter your AWS EC2 **Access Key** and **Secret Key.** +1. Click **Create.** + +**Result:** You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters. + +### 2. Create a node template with your cloud credentials and information from EC2 +Complete each of the following forms using information available from the [EC2 Management Console](https://aws.amazon.com/ec2). + +1. In the Rancher UI, click the user profile button in the upper right corner, and click **Node Templates.** +1. Click **Add Template.** +1. In the **Region** field, select the same region that you used when creating your cloud credentials. +1. In the **Cloud Credentials** field, select your newly created cloud credentials. +1. Click **Next: Authenticate & configure nodes.** +1. Choose an availability zone and network settings for your cluster. Click **Next: Select a Security Group.** +1. Choose the default security group or configure a security group. Please refer to [Amazon EC2 security group when using Node Driver]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#security-group-for-nodes-on-aws-ec2) to see what rules are created in the `rancher-nodes` Security Group. Then click **Next: Set Instance options.** +1. Configure the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI. + +> If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a [Kubernetes Cloud Provider]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers), you will need an additional permission in your policy. See [Example IAM policy with PassRole](#example-iam-policy-with-passrole) for an example policy. + +Optional: In the **Engine Options** section of the node template, you can configure the Docker daemon. You may want to specify the docker version or a Docker registry mirror. + +### 3. Create a cluster with node pools using the node template + +{{< step_create-cluster_node-pools >}} + +1. From the **Clusters** page, click **Add Cluster**. + +1. Choose **Amazon EC2**. + +1. Enter a **Cluster Name**. + +1. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created. + +1. Click **Add Member** to add users that can access the cluster. + +1. Use the **Role** drop-down to set permissions for each user. + +1. Use **Cluster Options** to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. Refer to [Selecting Cloud Providers]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) to configure the Kubernetes Cloud Provider. + +1. Click **Create**. + +{{< result_create-cluster >}} +{{% /tab %}} +{{% tab "Rancher prior to v2.2.0+" %}} 1. From the **Clusters** page, click **Add Cluster**. @@ -28,7 +88,7 @@ Use {{< product >}} to create a Kubernetes cluster in Amazon EC2. 1. {{< step_create-cluster_member-roles >}} -1. {{< step_create-cluster_cluster-options >}}Refer to [Selecting Cloud Providers]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) to configure the Kubernetes Cloud Provider.

+1. {{< step_create-cluster_cluster-options >}}Refer to [Selecting Cloud Providers]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) to configure the Kubernetes Cloud Provider. 1. {{< step_create-cluster_node-pools >}} @@ -36,23 +96,21 @@ Use {{< product >}} to create a Kubernetes cluster in Amazon EC2. 1. Complete each of the following forms using information available from the [EC2 Management Console](https://aws.amazon.com/ec2). - - **Account Access** is where you configure the region of the nodes, and the credentials (Access Key and Secret Key) used to create the machine. See [Prerequisites](#prerequisites) how to create the Access Key and Secret Key and the needed permissions. - - {{< step_create-cloud-credential >}} - - - **Zone and Network** configures the availability zone and network settings for your cluster. - - **Security Groups** creates or configures the Security Groups applied to your nodes. Please refer to [Amazon EC2 security group when using Node Driver]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#amazonec2-securitygroup-nodedriver) to see what rules are created in the `rancher-nodes` Security Group. - - **Instance** configures the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI. + - **Account Access** is where you configure the region of the nodes, and the credentials (Access Key and Secret Key) used to create the machine. See [Prerequisites](#prerequisites) how to create the Access Key and Secret Key and the needed permissions. + - **Zone and Network** configures the availability zone and network settings for your cluster. + - **Security Groups** creates or configures the Security Groups applied to your nodes. Please refer to [Amazon EC2 security group when using Node Driver]({{}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#security-group-for-nodes-on-aws-ec2) to see what rules are created in the `rancher-nodes` Security Group. + - **Instance** configures the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI.

- If you need to pass an **IAM Instance Profile Name** (not ARN), for example, when you want to use a [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers), you will need an additional permission in your policy. See [Example IAM policy with PassRole](#example-iam-policy-with-passrole) for an example policy. + If you need to pass an **IAM Instance Profile Name** (not ARN), for example, when you want to use a [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers), you will need an additional permission in your policy. See [Example IAM policy with PassRole](#example-iam-policy-with-passrole) for an example policy. - 1. {{< step_rancher-template >}} - 1. Click **Create**. - 1. **Optional:** Add additional node pools. -
+1. {{< step_rancher-template >}} +1. Click **Create**. +1. **Optional:** Add additional node pools. 1. Review your cluster settings to confirm they are correct. Then click **Create**. {{< result_create-cluster >}} +{{% /tab %}} +{{% /tabs %}} ### Example IAM Policy diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md index 5ca68abc076..a9d9c8e46fd 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md @@ -1,56 +1,84 @@ --- -title: Cluster Options +title: Cluster Configuration Reference weight: 2250 --- -As you configure a new cluster that's provisioned using [RKE]({{< baseurl >}}/rke/latest/en/), you can choose custom Kubernetes options. +As you configure a new cluster that's [provisioned using RKE]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), you can choose custom Kubernetes options. You can configure Kubernetes options one of two ways: - [Rancher UI](#rancher-ui): Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster. -- [Config File](#config-file): The cluster config file allows you to use any option offered by Kubernetes by specifying them in YAML. In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. +- [Cluster Config File](#cluster-config-file): Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML. -## Rancher UI +In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive. For more information, see the section about the [cluster config file.](#cluster-config-file) + +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) + - [Kubernetes cloud providers](#kubernetes-cloud-providers) + - [Private registries](#private-registries) + - [Authorized cluster endpoint](#authorized-cluster-endpoint) +- [Advanced Options](#advanced-options) + - [NGINX Ingress](#nginx-ingress) + - [Node port range](#node-port-range) + - [Metrics server monitoring](#metrics-server-monitoring) + - [Pod security policy support](#pod-security-policy-support) + - [Docker version on nodes](#docker-version-on-nodes) + - [Docker root directory](#docker-root-directory) + - [Recurring etcd snapshots](#recurring-etcd-snapshots) +- [Cluster config file](#cluster-config-file) + - [Config file structure in Rancher v2.3.0+](#config-file-structure-in-rancher-v2-3-0+) + - [Config file structure in Rancher v2.0.0-v2.2.x](#config-file-structure-in-rancher-v2-0-0-v2-2-x) + - [Default DNS provider](#default-dns-provider) +- [Rancher specific parameters](#rancher-specific-parameters) + +# Rancher UI Options When creating a cluster using one of the options described in [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters), you can configure basic Kubernetes options using the **Cluster Options** section. -From this section you can choose: +### Kubernetes Version -- The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on [hyperkube](https://github.com/rancher/hyperkube). +The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on [hyperkube](https://github.com/rancher/hyperkube). -- The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. For more details on the different networking providers, please view our [Networking FAQ]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/). +### Network Provider - >**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. +The [Network Provider](https://kubernetes.io/docs/concepts/cluster-administration/networking/) that the cluster uses. For more details on the different networking providers, please view our [Networking FAQ]({{< baseurl >}}/rancher/v2.x/en/faq/networking/cni-providers/). - Out of the box, Rancher is compatible with the following network providers: +>**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. - - [Canal](https://github.com/projectcalico/canal) +Out of the box, Rancher is compatible with the following network providers: - In v2.0.0 - v2.0.4 and v2.0.6, this was the default option for these clusters was Canal with network isolation. With the network isolation automatically enabled, it prevented any pod communication between [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). +- [Canal](https://github.com/projectcalico/canal) +- [Flannel](https://github.com/coreos/flannel#flannel) +- [Calico](https://docs.projectcalico.org/v3.11/introduction/) +- [Weave](https://github.com/weaveworks/weave) (Available as of v2.2.0) - As of v2.0.7, 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]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). +**Notes on Canal:** + +In v2.0.0 - v2.0.4 and v2.0.6, this was the default option for these clusters was Canal with network isolation. With the network isolation automatically enabled, it prevented any pod communication between [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). - >**Attention Rancher v2.0.0 - v2.0.6 Users** - > - >- In previous Rancher releases, Canal isolates project network communications with no option to disable it. If you are using any of these Rancher releases, be aware that using Canal prevents all communication between pods in different projects. - >- If you have clusters using Canal and are upgrading to v2.0.7, those clusters enable Project Network Isolation by default. If you want to disable Project Network Isolation, edit the cluster and disable the option. +As of v2.0.7, 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]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/). +>**Attention Rancher v2.0.0 - v2.0.6 Users** +> +>- In previous Rancher releases, Canal isolates project network communications with no option to disable it. If you are using any of these Rancher releases, be aware that using Canal prevents all communication between pods in different projects. +>- If you have clusters using Canal and are upgrading to v2.0.7, those clusters enable Project Network Isolation by default. If you want to disable Project Network Isolation, edit the cluster and disable the option. - - [Flannel](https://github.com/coreos/flannel#flannel) +**Notes on Flannel:** - In v2.0.5, this was the default option, which did not prevent any network isolation between projects. +In v2.0.5, this was the default option, which did not prevent any network isolation between projects. - - [Calico](https://docs.projectcalico.org/) - - [Weave](https://github.com/weaveworks/weave) (_Available as of v2.2.0_) +**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]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) and the [Weave Network Plug-in Options]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options). +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]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) and the [Weave Network Plug-in Options]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins/#weave-network-plug-in-options). +### Kubernetes Cloud Providers -
+You can configure a [Kubernetes cloud provider]({{}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage]({{}}/rancher/v2.x/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. -- If you want to configure a [Kubernetes cloud provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers). If you want to use [volumes and storage]({{< baseurl >}}/rancher/v2.x/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. - - >**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. +>**Note:** If the cloud provider you want to use is not listed as an option, you will need to use the [config file option](#config-file) to configure the cloud provider. Please reference the [RKE cloud provider documentation]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/) on how to configure the cloud provider. If you want to see all the configuration options for a cluster, please click **Show advanced options** on the bottom right. The advanced options are described below: @@ -81,42 +109,44 @@ For more detail on how an authorized cluster endpoint works and why it is used, We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the [recommended architecture section.]({{}}/rancher/v2.x/en/overview/architecture-recommendations/#architecture-for-an-authorized-cluster-endpoint) -### Advanced Cluster Options +# Advanced Options -#### Nginx Ingress +The following options are available when you create clusters in the Rancher UI. They are located under **Advanced Options.** + +### NGINX Ingress Option to enable or disable the [NGINX ingress controller]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/). -#### Node Port Range +### Node Port Range Option to change the range of ports that can be used for [NodePort services](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport). Default is `30000-32767`. -#### Metrics Server Monitoring +### Metrics Server Monitoring Option to enable or disable [Metrics Server]({{< baseurl >}}/rke/latest/en/config-options/add-ons/metrics-server/). -#### Pod Security Policy Support +### Pod Security Policy Support Option to enable and select a default [Pod Security Policy]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies). You must have an existing Pod Security Policy configured before you can use this option. -#### Docker version on nodes +### Docker Version on Nodes Option to require [a supported Docker version]({{< baseurl >}}/rancher/v2.x/en/installation/requirements/) installed on the cluster nodes that are added to the cluster, or to allow unsupported Docker versions installed on the cluster nodes. -#### Docker Root Directory +### Docker Root Directory If the nodes you are adding to the cluster have Docker configured with a non-default Docker Root Directory (default is `/var/lib/docker`), please specify the correct Docker Root Directory in this option. -#### Recurring etcd Snapshots +### Recurring etcd Snapshots Option to enable or disable [recurring etcd snapshots]({{< baseurl >}}/rke/latest/en/etcd-snapshots/#etcd-recurring-snapshots). -## Config File +# Cluster Config File + +Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{}}/rke/latest/en/config-options/) in an RKE installation, except for `system_images` configuration. The `system_images` option is not supported when creating a cluster with the Rancher UI or API. >**Note:** In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: `kube_api` and `kube_controller`. -Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the [options available]({{< baseurl >}}/rke/latest/en/config-options/) in an RKE installation, except for `system_images` configuration. The `system_images` option is not supported when creating a cluster with the Rancher UI or API. - - To edit an RKE config file directly from the Rancher UI, click **Edit as YAML**. - To read from an existing RKE file, click **Read from a file**. @@ -315,25 +345,25 @@ The table below indicates what DNS provider is deployed by default. See [RKE doc | v2.2.5 and higher | v1.13.x and lower | kube-dns | | v2.2.4 and lower | any | kube-dns | -### Rancher specific parameters +# Rancher specific parameters _Available as of v2.2.0_ Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML): -#### docker_root_dir +### docker_root_dir See [Docker Root Directory](#docker-root-directory). -#### enable_cluster_monitoring +### enable_cluster_monitoring Option to enable or disable [Cluster Monitoring]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/tools/monitoring/). -#### enable_network_policy +### enable_network_policy Option to enable or disable Project Network Isolation. -#### local_cluster_auth_endpoint +### local_cluster_auth_endpoint See [Authorized Cluster Endpoint](#authorized-cluster-endpoint). diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md index 0a08766d8bc..fe04895fd71 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/_index.md @@ -1,5 +1,5 @@ --- -title: Selecting Cloud Providers +title: Setting up Cloud Providers weight: 2255 aliases: - /rancher/v2.x/en/concepts/clusters/cloud-providers/ diff --git a/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/rancher-agents/_index.md similarity index 93% rename from content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md rename to content/rancher/v2.x/en/cluster-provisioning/rke-clusters/rancher-agents/_index.md index dfbe6716ebd..2e3b1e0678a 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/rancher-agents/_index.md @@ -1,6 +1,8 @@ --- -title: Rancher agents +title: Rancher Agents weight: 2400 +aliases: + - /rancher/v2.x/en/cluster-provisioning/rancher-agents --- There are two different agent resources deployed on Rancher managed clusters: @@ -8,7 +10,7 @@ There are two different agent resources deployed on Rancher managed clusters: - [cattle-cluster-agent](#cattle-cluster-agent) - [cattle-node-agent](#cattle-node-agent) -For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) +For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the [architecture]({{}}/rancher/v2.x/en/overview/architecture/) ### cattle-cluster-agent diff --git a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md index 9042b9c9857..8f1cfe92645 100644 --- a/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md +++ b/content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md @@ -1,5 +1,5 @@ --- -title: Configuring Custom Clusters for Windows +title: Launching Kubernetes on Windows Clusters weight: 2240 --- diff --git a/content/rancher/v2.x/en/overview/_index.md b/content/rancher/v2.x/en/overview/_index.md index 7a913064129..92c84b5cb81 100644 --- a/content/rancher/v2.x/en/overview/_index.md +++ b/content/rancher/v2.x/en/overview/_index.md @@ -58,10 +58,10 @@ The options and settings available for an existing cluster change based on the m After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among [other options.]({{}}/rancher/v2.x/en/cluster-admin/editing-clusters/) -The following table shows an overview of the options and settings available for each cluster type: +The following table summarizes the options and settings available for each cluster type: - Cluster Type | Manage Member Roles | Edit Cluster Options | Manage Node Pools ----------|----------|---------|---------| - [RKE-Launched]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#rancher-launched-kubernetes) | ✓ | ✓ | ✓ | - [Hosted Kubernetes Cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#hosted-kubernetes-cluster) | ✓ | | | - [Imported]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#import-existing-cluster) | ✓ | | | \ No newline at end of file + Rancher Capability | RKE Launched | Hosted Kubernetes Cluster | Imported Cluster + ---------|----------|---------|---------| + Manage member roles | ✓ | ✓ | ✓ + Edit cluster options | ✓ | | + Manage node pools | ✓ | | \ No newline at end of file diff --git a/layouts/shortcodes/step_create-cloud-credential.html b/layouts/shortcodes/step_create-cloud-credential.html deleted file mode 100644 index 1cc2891c0b5..00000000000 --- a/layouts/shortcodes/step_create-cloud-credential.html +++ /dev/null @@ -1,6 +0,0 @@ -

-As of v2.2.0, account access information will be stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. -
-Since multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. To create a new cloud credential, enter Name and Account Access data, then click Create. -
-
diff --git a/layouts/shortcodes/step_create-cluster_node-pools.html b/layouts/shortcodes/step_create-cluster_node-pools.html index 158eaf7f1f3..ada69c017f6 100644 --- a/layouts/shortcodes/step_create-cluster_node-pools.html +++ b/layouts/shortcodes/step_create-cluster_node-pools.html @@ -1,4 +1,4 @@ -

Add one or more node pools to your cluster.

A node pool is a collection of nodes based on a node template. A node Template defines the configuration of a node, like what Operating System to use, number of CPUs and amount of memory. Each node pool must have one or more nodes roles assigned.

+

Add one or more node pools to your cluster.

A node pool is a collection of nodes based on a node template. A node template defines the configuration of a node, like what operating system to use, number of CPUs and amount of memory. Each node pool must have one or more nodes roles assigned.

Notes:

diff --git a/layouts/shortcodes/step_rancher-template.html b/layouts/shortcodes/step_rancher-template.html index 0323edb2d58..96a1584194c 100644 --- a/layouts/shortcodes/step_rancher-template.html +++ b/layouts/shortcodes/step_rancher-template.html @@ -1,19 +1,24 @@ -

Complete the Rancher Template form to configure the Docker daemon on the instances that will be created.

+

The Docker daemon configuration options include:

  • -

    Labels can be configured on the Docker daemon.

    - -

    Docker object label documentation

    +

    + Labels: For information on labels, refer to the Docker + object label documentation. +

  • - -

    Engine Options customize the configuration of the Docker daemon. Important configuration options might include: -

      -
    • Docker Engine Install URL: Determines what Docker version will be installed on the instance.

      When using RancherOS, please check what Docker versions are available using sudo ros engine list on the RancherOS version you want to use, as the default Docker version configured might not be available. If you experience issues installing Docker on other operating systems, please try to install Docker manually using the configured Docker Engine Install URL to troubleshoot.
      • -
    • Registry mirrors: Docker Registry mirror to be used by the Docker daemon
      • -
    +

    + Docker Engine Install URL: Determines what Docker version will be installed on the instance. Note: If you are using RancherOS, please check what Docker versions are available using sudo ros engine list on the RancherOS version you want to use, as the default Docker version configured might not be available. If you experience issues installing Docker on other operating systems, please try to install Docker manually using the configured Docker Engine Install URL to troubleshoot.

    - -

    Docker daemon option reference

    +
    • +
  • +

    + Registry mirrors: Docker Registry mirror to be used by the Docker daemon +

    +
    • +
  • +

    Other advanced options: Refer to the Docker daemon option reference + +