From c647774db5b2651c0f7412dd64ff8fea45c5e8f9 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Tue, 17 Apr 2018 17:06:09 -0700 Subject: [PATCH 1/7] initial check in for a gang of cluster creation and general configuration docs. --- content/rancher/about/_index.md | 0 content/rancher/concepts/authentication.md | 12 + content/rancher/concepts/users-and-roles.md | 43 +++ content/rancher/installation/requirements.md | 50 +++ content/rancher/quick-start-guide/_index.md | 339 ++++-------------- .../create-cluster-amazon-ec2.md | 69 ++++ .../create-cluster-azure-container-service.md | 38 ++ .../create-cluster-azure.md | 65 ++++ .../create-cluster-custom.md | 69 ++++ .../create-cluster-digital-ocean.md | 65 ++++ .../creating-a-cluster/create-cluster-gke.md | 59 +++ .../create-cluster-vsphere.md | 66 ++++ .../rancher/tasks/clusters/import-cluster.md | 31 ++ .../tasks/global-configuration/_index.md | 0 .../configure-user-authentication.md | 87 +++++ .../pod-security-policies.md | 28 ++ .../tasks/global-configuration/roles.md | 35 ++ .../tasks/global-configuration/server-url.md | 17 + content/rancher/tasks/miscellaneous/_index.md | 0 content/rancher/tasks/pipelines/_index.md | 0 content/rancher/tasks/projects/_index.md | 0 content/rancher/tasks/users/_index.md | 0 content/rancher/tasks/workloads/_index.md | 0 layouts/shortcodes/prereq_cluster.html | 5 + layouts/shortcodes/product.html | 1 + layouts/shortcodes/result_create-cluster.html | 8 + .../step_create-cluster_cluster-options.html | 1 + .../step_create-cluster_member-roles.html | 8 + .../step_create-cluster_node-pools.html | 10 + layouts/shortcodes/step_rancher-template.html | 14 + layouts/shortcodes/version.html | 1 + 31 files changed, 842 insertions(+), 279 deletions(-) create mode 100644 content/rancher/about/_index.md create mode 100644 content/rancher/concepts/authentication.md create mode 100644 content/rancher/concepts/users-and-roles.md create mode 100644 content/rancher/installation/requirements.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-digital-ocean.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-gke.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/create-cluster-vsphere.md create mode 100644 content/rancher/tasks/clusters/import-cluster.md create mode 100644 content/rancher/tasks/global-configuration/_index.md create mode 100644 content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md create mode 100644 content/rancher/tasks/global-configuration/pod-security-policies.md create mode 100644 content/rancher/tasks/global-configuration/roles.md create mode 100644 content/rancher/tasks/global-configuration/server-url.md create mode 100644 content/rancher/tasks/miscellaneous/_index.md create mode 100644 content/rancher/tasks/pipelines/_index.md create mode 100644 content/rancher/tasks/projects/_index.md create mode 100644 content/rancher/tasks/users/_index.md create mode 100644 content/rancher/tasks/workloads/_index.md create mode 100644 layouts/shortcodes/prereq_cluster.html create mode 100644 layouts/shortcodes/product.html create mode 100644 layouts/shortcodes/result_create-cluster.html create mode 100644 layouts/shortcodes/step_create-cluster_cluster-options.html create mode 100644 layouts/shortcodes/step_create-cluster_member-roles.html create mode 100644 layouts/shortcodes/step_create-cluster_node-pools.html create mode 100644 layouts/shortcodes/step_rancher-template.html create mode 100644 layouts/shortcodes/version.html diff --git a/content/rancher/about/_index.md b/content/rancher/about/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/concepts/authentication.md b/content/rancher/concepts/authentication.md new file mode 100644 index 00000000000..9cc8fc71317 --- /dev/null +++ b/content/rancher/concepts/authentication.md @@ -0,0 +1,12 @@ +# Authentication + +One of the key features that {{< product >}} adds to Kubernetes is enhanced user authentication. + +By default, Kubernetes has some authentication shortcomings. Namely, users and groups are tied to the two scopes that Kubernetes uses to group resources: global and namespace. These scopes make it difficult to manage users and groups across different clusters and namespaces. Kubenetes allows integration with other authentication providers that work around these issues using plugins. However, this integration is not available to those leveraging cloud-based Kubenetes offerings such as Google Container Engine (GKE). + +Rancher improves on Kubernetes authentication by integrating external authentication. Out-of-the-box, Rancher provides integration with the following authentication services: + + - Microsoft Active Directory + - GitHub + +## External vs. Local Authentication diff --git a/content/rancher/concepts/users-and-roles.md b/content/rancher/concepts/users-and-roles.md new file mode 100644 index 00000000000..be5042709aa --- /dev/null +++ b/content/rancher/concepts/users-and-roles.md @@ -0,0 +1,43 @@ +# Users and Roles + +Every user in {{< product >}} is assigned a _role_, which is a set of permissions that determine what Kubenetes API endpoints that the user can access. Let's use this metaphor: a user account is like getting access to an entire office building; however, the user's role determine what rooms the user can access within the building. + +Within {{< product >}} there are two types of user roles: + +- [Default roles](#default-roles) +- [Custom roles](#custom-roles) + +In addition, [_Membership_](#membership) plays a part in user access. Membership determines the scope of a user's role. + +## Default Roles + +Out-of-the-box, {{< product >}} comes with two default roles that fulfill most use cases: + +- **Administrators** + + Admins have global access to all Rancher clusters and projects, as well as all permissions. Admins are the "Cow Bosses" of {{< product >}}. + +- **Standard Users** + + If Administrators are the "Cow Bosses" of {{< product >}}, then Standard Users are the "Cowboys." + + Standard users can: + + - Create new clusters + - Manage clusters and projects they hold membership in.
+ + >**Note:** To authorize Standard Users for existing clusters and projects, you must explicitly add the user as a cluster/project member. + + + +## Custom Roles + +If neither of the default roles suit your use case, you can create a _custom role_. While creating a custom role, you can choose the individual roles and permissions for a user within {{< product >}}. Custom roles are helpful when you need to give a user one specific permission without giving them access to the entire system. + +## Membership + +Within {{< product >}}, users and roles are further refined with _membership_. Each cluster and project includes a pool of users who hold membership in that object. Membership allows you to define a scope where a given user's permissions are authorized. + +- All users assigned the Administrator role hold membership in all clusters and projects. + +- Before a user assigned either the standard user or custom role can work in an existing cluster or project, the user must be explicitly added as a member. diff --git a/content/rancher/installation/requirements.md b/content/rancher/installation/requirements.md new file mode 100644 index 00000000000..9afea7f2a45 --- /dev/null +++ b/content/rancher/installation/requirements.md @@ -0,0 +1,50 @@ +# Rancher Requirements + +#### Hardware Requirements + +- Memory: 4GB + +#### Software requirements + +- Operating System: Ubuntu 16.04 (64-bit) +- Software: Docker + + **Supported Versions:** + + - `1.12.6` + - `1.13.1` + - `17.03.2` + + >**Notes:** + > + > * For Docker installation instructions, visit their [documentation](https://docs.docker.com/install/). + > * Docker requirements apply to both your Linux host and your cluster nodes. + +#### Port Requirements + +When provisioning your Linux host, open the ports listed below so that your master and worker nodes can communicate. + +##### Master Nodes (etcd and controlplane nodes) + +Protocol | Direction | Port Range | Purpose +--|---|---|-- +TCP | Inbound | 22 | SSH server +TCP | Inbound | 80 | Canal +TCP | Inbound | 443 | Canal +TCP | Inbound | 6443 | Kubernetes API server +TCP | Inbound | 2379-2380 | etcd server client API +TCP | Inbound | 10250 | kubelet API +TCP | Inbound | 10251 | scheduler +TCP | Inbound | 10252 | controller +TCP | Inbound | 10256 | kubeproxy + +##### Worker Nodes + +Protocol | Direction | Port Range | Purpose +--|---|---|-- +TCP | Inbound | 22 | SSH Server +TCP | Inbound | 80 | Canal +TCP | Inbound | 443 | Canal +TCP | Inbound | 10250 | kubelet API +TCP | Inbound | 10256 | kubeproxy +TCP | Inbound | 30000-32767 | NodePort Services diff --git a/content/rancher/quick-start-guide/_index.md b/content/rancher/quick-start-guide/_index.md index 16783d989c0..1a7ce4da78d 100644 --- a/content/rancher/quick-start-guide/_index.md +++ b/content/rancher/quick-start-guide/_index.md @@ -6,50 +6,55 @@ title: Quick Start Guide weight: 2 --- -Quick Start Guide ---- +# Quick Start Guide -This tutorial walks you through installation of Rancher v2.0, creation of your first cluster, and deployment of an application. +Howdy Partner! This tutorial walks you through: ->**Note:** Upgrades are not supported during the Rancher v2.0 beta. +- Installation of {{< product >}} {{< version >}} +- Creation of your first cluster +- Deployment of an application, NGINX -### Objectives +## Objectives -Creation of your first cluster is a multi-stage process that we've broken into different tasks. +This Quick Start Guide is divided into different tasks for easier consumption. -1. [Review Requirements](#host-and-node-requirements) +1. [Provision a Linux Host](#provision-a-linux-host) - Before you do anything, review the requirements. + Begin by provisioning a Linux host. -2. [Prepare a Linux Host](#prepare-a-linux-host) +2. [Install Rancher](#install-rancher) - First, you need to provision a Linux host. + From your Linux host, run the Docker command for installing Rancher. -3. [Install Rancher](#install-rancher) - - Run the Docker command for installing Rancher. - -4. [Log In](#log-in) +3. [Log In](#log-in) Browse to your Linux host to access the Rancher UI. -5. [Create a Cluster](#create-a-cluster) +4. [Create the Cluster](#create-the-cluster) - Use Rancher to create your first cluster. + Use the versatile **Custom** option to clone your Linux host into a new Kubernetes cluster. -6. [Deploy a Workload](#deploy-a-workload) +5. [Deploy a Workload](#deploy-a-workload) - Create a workload so that Kubernetes can distribute an application and its dependencies among your nodes. + Create a workload so that Kubernetes can distribute NGINX among your cluster nodes. -7. [View Your Application](#view-your-application) +6. [View Your Application](#view-your-application) - When your workload finishes deployment, browse to your application to make sure it works. + When your workload finishes deployment, browse to your node IP to make sure NGINX is running. -8. [What's Next?](#whats-next) +7. [What's Next?](#whats-next) - Now that you've created a cluster and deployed a workload, find out what else you can do with Rancher v2.0. + Now that you've created a cluster and deployed NGINX, find out what else you can do with Rancher v2.0. -### Host and Node Requirements +## Provision a Linux Host + +Begin creation of a custom cluster by provisioning a Linux host. Your host can be: + +- A cloud-host virtual machine (VM) +- An on-premise VM +- A bare-metal server + +Provision the host according to the requirements below. #### Hardware Requirements @@ -71,45 +76,6 @@ Creation of your first cluster is a multi-stage process that we've broken into d > * For Docker installation instructions, visit their [documentation](https://docs.docker.com/install/). > * Docker requirements apply to both your Linux host and your cluster nodes. -#### Port Requirements - -When provisioning your Linux host, open the ports listed below so that your master and worker nodes can communicate. - -##### Master Nodes (etcd and controlplane nodes) - -Protocol | Direction | Port Range | Purpose ---|---|---|-- -TCP | Inbound | 22 | SSH server -TCP | Inbound | 80 | Canal -TCP | Inbound | 443 | Canal -TCP | Inbound | 6443 | Kubernetes API server -TCP | Inbound | 2379-2380 | etcd server client API -TCP | Inbound | 10250 | kubelet API -TCP | Inbound | 10251 | scheduler -TCP | Inbound | 10252 | controller -TCP | Inbound | 10256 | kubeproxy - -##### Worker Nodes - -Protocol | Direction | Port Range | Purpose ---|---|---|-- -TCP | Inbound | 22 | SSH Server -TCP | Inbound | 80 | Canal -TCP | Inbound | 443 | Canal -TCP | Inbound | 10250 | kubelet API -TCP | Inbound | 10256 | kubeproxy -TCP | Inbound | 30000-32767 | NodePort Services - -### Prepare a Linux Host - -Begin by provisioning a Linux host to be your Rancher server and a template for your cluster nodes. This host can be: - -- A virtual machine hosted by a cloud service. -- An on-premise virtual machine. -- An on-premise bare-metal server. - -Provision the server according to the [requirements above](#host-and-node-requirements). - ### Install Rancher To install Rancher on your host, connect to it and then use a shell to install. @@ -119,16 +85,11 @@ To install Rancher on your host, connect to it and then use a shell to install. 2. From your shell, enter the following command: ``` - $ sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/server:preview + $ sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/server ``` - >**Note:** - > Although Rancher v2.0 is in beta, the `preview` tag is still used for installation. - **Result:** Rancher is installed. - - ### Log In Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations. @@ -139,131 +100,65 @@ Log in to Rancher to begin using the application. After you log in, you'll make Replace `` with your host IP address. - > **Note:** Rancher v2.0 beta: - > - > - Supports only the HTTPS protocol. - > - Uses a self-signed certificate. Due to this signature, the browser prompts you to trust the certificate before login. Following GA, you'll be able to use your own certificate. - 2. When prompted, create a password for the default `admin` account there cowpoke! - ![login](../../../../img/rancher/change-password.png) +3. Set the **Rancher Server URL**. The URL can either be an IP address or a host name. However, each node in your cluster must be able to resolve to the URL. +## Create the Cluster -4. Set the **Rancher Server URL**. The URL can either be an IP or a host name. However, each of your cluster nodes must be able to resolve to the URL. +Welcome to {{< product >}}! Use our application to clone your Linux host and configure them as a Kubernetes cluster. - ![login](../../../../img/rancher/server-url.png) +In this task, use the versatile **Custom** option. This option lets you convert _any_ Linux host (cloud-hosted VM, on-premise VM, or bare-metal) into a cluster. -### Create a Cluster +1. From the **Clusters** page, click **Add Cluster**. -Begin using Rancher by creating your first cluster! A *cluster* is a group of physical (or virtual) computers that share resources to accomplish tasks as if they were a single system. +2. Choose **Custom**. -1. Click **+ Add Cluster**. +3. Enter a **Cluster Name**. - ![add cluster](../../../../img/rancher/click-add-cluster.png) +4. Skip **Member Roles** and **Cluster Options**. We'll tell you about them later. - **Step Result:** The **Add Cluster** page opens. +5. Click **Next**. -2. From the **Add Cluster** menu, choose a service or source from which to create your first cluster. +6. From **Node Role**, select _all_ the roles: **etcd**, **Control**, and **Worker**. - * If you're using a virtual machine hosted on a major cloud service, choose the tile for the service you want to use (e.g. **Digital Ocean**, **Azure Container Service**). - * If you're using bare-metal server, an on-premise virtual machine, or a cloud service that isn't explicitly listed, choose **Custom**. +7. Skip the **Labels** stuff. It's not important for now. - > **Note:** - > - > - For Rancher v2.0 beta, Amazon EKS is not supported. This option will be available after GA. - > - For this tutorial, the Import option is out of scope. For now, create a cluster using one of the other options. We'll address Import later. +8. Copy the command displayed on screen to your clipboard. -3. Enter a **Cluster Name**. No spaces allowed. +9. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. - > **Tip:** Skip adding **Member Roles** for now. This option isn't essential for your first cluster. - > - > ![skip member roles](../../../../img/rancher/skip-member-roles.png) +10. When you finish running the command on your Linux host, click **Done**. -4. **For those using Google Container Engine or Azure Container Service:** - - Complete the form asking for account information. The form includes links to instructions detailing how to obtain this info. - - ![gce-azure-instructions](../../../../img/rancher/gce-azure-instructions.png) - - **Did you choose one of the other tiles (like Digital Ocean)?** This step doesn't apply to you. Skip to the next step. - -5. Select **Cluster Options**. - - Use these options to choose things like the version of Kubernetes that's installed in your cluster, along with other Kubernetes options such as pod security policies. Some services have more options than others. If you're unsure of what to choose, use the default options. - -6. Add at least one **Node Pool**. - - A *Node Pool* is a group of nodes that are configured identically. Your cluster can contain as many node pools as you'd like. Each object in the grid represents a single node configuration. You can use the node pool to choose the number (i.e. **Count**) of nodes running a given configuration (i.e. **Template**). - - > **Note:** The instructions below don't apply to Google Container Engine, Azure Container Service, or the Custom option. - > - >* For Azure Container Server, no additional steps are needed. Proceed to this task's [final step](#create-cluster). - >* For Google Container Engine, complete the Nodes form. The options are pretty self-explanatory. When you're done, proceed to this task's [final step](#create-cluster). - >* For Custom, see [Appendix A: Add Custom Cluster](#appendix-a-add-custom-cluster). - - 1. Enter a **Node Prefix**. When the cluster is created, each node in the pool is named after the prefix. An incremented number is appended to each node. - - 2. Enter the node **Count** for the pool. - - 3. Click **Add Node Template**. A node template is just the a virtual machine configuration you're using to create your nodes (i.e. other virtual machines). - - Depending on the cluster option that you choose, the Rancher UI displays instructions on how to create a template. The process is different for each cloud service. You may need to log in to your cloud service to find the data Rancher needs. - - 4. Choose the **Template** that you just added. - - ![choose template](../../../../img/rancher/choose-template.gif) - - 5. Select roles for the node pool. - - Kubernetes functions using different [components](https://kubernetes.io/docs/concepts/overview/components/), which are divided into *master components* and *node components*. When setting up your node pool, select a pool to fill each component role. You can install all components one a single pool, or you can spread them around. - - The roles are: - - - **etcd**: One of the master components. Etcd is a distributed reliable key-value store that stores all Kubernetes states. - - - **Control**: The remaining master components as well as the node components. These nodes help manage the Kubernetes cluster and where your applications can be launched. - - - **Worker**: On these nodes, only node components are launched. These nodes run only applications. - - 6. **Optional:** Click **+ Add Node Pool** to add more pools. - - ![add-second-node-pool](../../../../img/rancher/add-second-node-pool.gif) - - 7. Click **Create**. - -**Result:** - -- Your cluster is created and assigned a state of **Provisioning**. Rancher is standing up your cluster. -- You can access your cluster after its state is updated to **Active**. -- **Active** clusters are assigned a **Project** and **Namespace**, both of which are named `Default`. +{{< result_create-cluster >}} ### Deploy a Workload -You're ready to create your first *workload*. A workload is an object that includes pods along with other files and info needed to deploy your application. +You're ready to create your first _workload_. A workload is an object that includes pods along with other files and info needed to deploy your application. -1. From the **Clusters** page, open the cluster that you just created. +For this workload, you'll be deploying the application NGINX. -2. From the main menu of the **Dashboard**, select **Projects**. +1. From the **Clusters** page, open the cluster that you just created. -3. Open the **Default** project. +2. From the main menu of the **Dashboard**, select **Projects**. -4. Click **+ Deploy**. +3. Open the **Default** project. - ![click-deploy](../../../../img/rancher/click-deploy.png) +4. Click **+ Deploy**. - **Step Result:** The **Deploy Workload** page opens. + **Step Result:** The **Deploy Workload** page opens. -5. Enter a **Name** for your workload. No spaces allowed. +5. Enter a **Name** for your workload. -6. From the **Docker Image** field, enter the name of an image hosted on [Docker Hub](https://hub.docker.com/explore/). +6. From the **Docker Image** field, enter `nginx`. - We're going to use **NGINX** for this guide. You can use something else, but keep it simple. If your app needs other components to run, the deployment won't work. +7. From **Port Mapping**, click **Add Port**. - ![enter-docker-image](../../../../img/rancher/enter-docker-image.png) +8. From the **Publish on** drop-down, make sure that **Every node** is selected. -7. From the **Container Port** field, enter `80`. +8. From the **Source Port** field, leave the **Random** value in place. - >**Note:** During Rancher v2.0 beta, only port 80 is supported. Other ports will be supported at GA. +7. From the **Container Port** field, enter port `80`. 8. Leave the remaining options on their default setting. We'll tell you about them later. @@ -276,127 +171,13 @@ You're ready to create your first *workload*. A workload is an object that inclu ### View Your Application -When your workload completes deployment, browse to your application to confirm that it's working. +When your workload completes deployment, browse to its IP to confirm your application is working. From the **Workloads** page, click the link underneath your workload. If your deployment succeeded, your application opens. -![test-deployment](../../../../img/rancher/test-deployment.png) - - ### What's Next? Congratulations! You have: - Created your first cluster. -- Deployed an application to your cluster using a workload. - -Now you can use the rest of Rancher v2.0 to orchestrate and manage your pods. - -(Moooooo-re coming soon!) - -![cow](../../../../img/rancher/cow.jpg) - - -### Appendix A: Add Custom Cluster - -When creating a custom cluster, follow these instructions to complete its creation. These instructions will create one or more node that will be used to image your cluster. - ->**Note:** When creating a custom cluster, make sure each node meets the [Host Requirements](#host-requirements). - -1. From **Node Roles**, choose the Kubernetes component roles that you want the node to fill. You must fill each role. - - A more detailed description of each [role](#roles) is available earlier in this guide. - - >**Note:** If you want to spread the roles among different nodes, provision additional Linux hosts and enter the command on each of your nodes. - -3. **Optional:** Add labels to the node template. - -4. Copy the command for installing Docker to your clipboard. - - >**Remember:** The version of Docker installed on your nodes must be [supported](#node-requirements). - -5. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. - -6. Enter the command on your Linux host. - -7. From you Rancher session, click **Done**. - -8. Resume the Quick Start Guide from [Deploy a Workload](#deploy-a-workload). - - +- Deployed NGINX to your cluster using a workload. diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2.md new file mode 100644 index 00000000000..57029ea7d80 --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-amazon-ec2.md @@ -0,0 +1,69 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Amazon EC2 +weight: 20 +--- + +# Creating an Amazon EC2 Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create an Instance](#create-an-instance) + + Begin by logging into Amazon EC2 website and provisioning a new instance. + +2. [Create the Cluster](#create-the-amazon-ec2-cluster) + + Use your new instance as a template for your new Kubernetes cluster. + +## Create an Instance + +Create an _instance_, Amazon's version of a virtual machine in EC2, using the [Amazon EC2 Management Console](https://aws.amazon.com/ec2/). + +Provision the instance according to our [requirements](../setup/requirements.md). + +[Amazon Instructions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) + +## Create the Amazon EC2 Cluster + +Use {{< product >}} to clone your Linux host and configure them as Kubernetes nodes. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Amazon EC2**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. {{< step_create-cluster_node-pools >}} + + 1. Click **Add Node Template**. + + 2. Complete each of the following forms using information available from the [EC2 Management Console](https://aws.amazon.com/ec2). + + - **Account Access** holds the region and API Key used to create the cluster. + + [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) + + - **Zone and Network** configures the availability zone and network settings for your cluster. + + - **Security Groups** configures the security groups applied to your cluster. + + - **Instance** provisions your VM instances. + + 3. {{< step_rancher-template >}} + + 4. Click **Create**. + + 5. **Optional:** Add additional node pools. +
+6. Review your cluster settings to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md new file mode 100644 index 00000000000..71fa20d9ebb --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md @@ -0,0 +1,38 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Azure Container Service +weight: 30 +--- + +# Creating an Azure Container Service Cluster + +You can use Rancher to create a cluster using Microsoft Azure Container Service. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Azure Container Service**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. Complete the **Account Access** form. This information is used to authenticate with Azure. + + - You can find your **Subscription ID** and **Tenant ID** on the [Microsoft Azure Portal](https://portal.azure.com/). + - To obtain a **Client ID** and **Client Secret**, follow the instructions in [this document](https://www.packer.io/docs/builders/azure-setup.html). +
+7. Use **Nodes** to provision each node in your cluster and choose a geographical region. + + Provision the nodes according to our [requirements](../setup/requirements.md). + + [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys) +
+8. Click **Create**. +
+9. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure.md new file mode 100644 index 00000000000..bcc7ea7523c --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure.md @@ -0,0 +1,65 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Azure +weight: 50 +--- + +# Creating an Azure Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create a Linux Virtual Machine](#create-a-linux-virtual-machine) + + Begin by logging into Azure and provisioning a Linux virtual machine (VM). + +2. [Create the Cluster](#create-the-azure-cluster) + + Use your Linux VM as a template for your new Kubernetes cluster. + +## Create a Linux Virtual Machine + +Create a Linux VM using the [Microsoft Azure Portal](https://portal.azure.com) ([Azure Instructions](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/)). + +Provision the droplet according to our [requirements](../setup/requirements.md). + +## Create the Azure Cluster + +Use {{< product >}} to clone your Linux host and configure them as Kubernetes nodes. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Azure**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. {{< step_create-cluster_node-pools >}} + + 1. Click **Add Node Template**. + + 2. Complete the **Azure Options** form. + + - **Placement** sets the geographical region where where your cluster is hosted and other location metadata. + + - **Account Access** stores your account information for authenticating with Azure. + + - **Network** configures the networking used in your cluster. + + - **Instance** customizes your VM configuration. + + 3. {{< step_rancher-template >}} + + 4. Click **Create**. + + 5. **Optional:** Add additional node pools. + +7. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md new file mode 100644 index 00000000000..7d0da2efb9d --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md @@ -0,0 +1,69 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Custom Cluster +weight: 10 +--- + +# Creating a Custom Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create a Linux Host](#create-a-linux-host) + + Begin by provisioning a Linux host. + +2. [Create the Cluster](#create-the-custom-cluster) + + Use your new Linux host as a template for your new Kubernetes cluster. + +## Provision a Linux Host + +Begin creation of a custom cluster by provisioning a Linux host. Your host can be: + +- A cloud-host virtual machine (VM) +- An on-premise VM +- A bare-metal server + +Provision the host according to our [requirements](../setup/requirements.md). + +>**Bare-Metal Server Note:** +> +While creating your cluster, you must assign Kubernetes roles to your cluster nodes. If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). + +## Create the Custom Cluster + +Use {{< product >}} to clone your Linux host and configure them as Kubernetes nodes. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Custom**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. Click **Next**. + +7. From **Node Role**, choose the roles that you want filled by a cluster node. + + >**Bare-Metal Server Reminder:** + > + If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). + +8. **Optional**: Use **Labels** to add metadata so that you can find them later. + +9. Copy the command displayed on screen to your clipboard. + +10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. + + >**Note:** Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed. + +11. When you finish running the command(s) on your Linux host(s), click **Done**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-digital-ocean.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-digital-ocean.md new file mode 100644 index 00000000000..b5ee567f469 --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-digital-ocean.md @@ -0,0 +1,65 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: DigitalOcean +weight: 60 +--- + +# Creating a DigitalOcean Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create a Droplet](#create-a-droplet) + + Begin by logging into DigitalOcean and provisioning a new droplet. + +2. [Create the Cluster](#create-the-digital-ocean-cluster) + + Use your new droplet as a template for your new Kubernetes cluster. + +## Create a Droplet + +Create a _droplet_, DigitalOcean's name for a virtual machine, using the DigitalOcean website. + +Provision the droplet according to our [requirements](../setup/requirements.md). + +[DigitalOcean Instructions](https://www.digitalocean.com/community/tutorials/how-to-create-your-first-digitalocean-droplet) + +## Create the DigitalOcean Cluster + +Use {{< product >}} to clone your Linux host and configure them as Kubernetes nodes. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Digital Ocean**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. {{< step_create-cluster_node-pools >}} + + 1. Click **Add Node Template**. + + 2. Paste your DigitalOcean Personal Access Token. + + [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) + + 3. Complete the **DigitalOcean Options** form. + + - **Droplet Options** provision your cluster's geographical region and specifications. + + 4. {{< step_rancher-template >}} + + 5. Click **Create**. + + 6. **Optional:** Add additional node pools. +
+7. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-gke.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-gke.md new file mode 100644 index 00000000000..540ec59c92d --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-gke.md @@ -0,0 +1,59 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Google Container Engine +weight: 70 +--- + +# Creating a Google Container Engine Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create a Service Account](#create-a-gke-service-account) + + Begin by logging into Google Cloud Platform and creating a service account to operate your cluster. + +2. [Create the Cluster](#create-the-gke-cluster) + + Using your service account, create your Google Container Engine (GKE) cluster. + +## Create a Service Account + +Create a service account using [Google Cloud Platform](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: + +- `project/viewer` +- `kubernetes-engine/admin` +- `service-account/user` + +[Google Documentation: Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) + +## Create the GKE Cluster + +Use {{< product >}} to set up and configure your Kubernetes cluster. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **Google Container Engine**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. Either paste your service account private key in the **Service Account** text box or **Read from a file**. Then click **Next: Configure Nodes**. + + >**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. {{< step_create-cluster_cluster-options >}} + +7. Use **Nodes** to provision each node in your cluster and choose a geographical region. + + Provision the nodes according to our [requirements](../setup/requirements.md). + +8. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-vsphere.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-vsphere.md new file mode 100644 index 00000000000..74ca9233c48 --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-vsphere.md @@ -0,0 +1,66 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: vSphere +weight: 80 +--- + +# Creating a vSphere Cluster + +## Objectives + +{{< prereq_cluster >}} + +1. [Create a Linux Virtual Machine](#create-a-linux-virtual-machine) + + Begin by logging into vSphere and provisioning a Linux virtual machine (VM). + +2. [Create the Cluster](#create-the-vsphere-cluster) + + Use your new VM as a template for your new Kubernetes cluster. + +## Create a Linux Virtual Machine + +Create a Linux VM using vSphere. + +Provision the droplet according to our [requirements](../setup/requirements.md). + +[VMware Instructions](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vm_admin.doc/GUID-39D19B2B-A11C-42AE-AC80-DDA8682AB42C.html) + +## Create the vSphere Cluster + +Use {{< product >}} to clone your Linux host and configure them as Kubernetes nodes. + +1. From the **Clusters** page, click **Add Cluster**. + +2. Choose **vSphere**. + +3. Enter a **Cluster Name**. + +4. {{< step_create-cluster_member-roles >}} + +5. {{< step_create-cluster_cluster-options >}} + +6. {{< step_create-cluster_node-pools >}} + + 1. Click **Add Node Template**. + + 2. Use the **vSphere Options** to authenticate with vSphere and provision your cluster. + + - **Account Access** holds the host name for your vCenter host and your credentials for authentication. + + - **Instance Options** are used to provision your cluster's VMs. + + - **Scheduling** is used to choose the hypervisor your virtual machines will be scheduled to. + + 3. {{< step_rancher-template >}} + + 4. Click **Create**. + + 5. **Optional:** Add additional node pools. + +
+7. Review your options to confirm they're correct. Then click **Create**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/clusters/import-cluster.md b/content/rancher/tasks/clusters/import-cluster.md new file mode 100644 index 00000000000..31e7bfcac49 --- /dev/null +++ b/content/rancher/tasks/clusters/import-cluster.md @@ -0,0 +1,31 @@ +--- +tag: ["rancher", "cluster"] +category: "rancher" +layout: list-docs +title: Importing a Cluster +weight: 90 +--- + +# Importing a Cluster + +You can import an existing Kubernetes cluster and then manage it using Rancher. + +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. Copy the first command displayed to your clipboard. + +7. Log into one of your cluster nodes using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard. + +8. If you receive a message of `certificate signed by unknown authority`, copy the second command displayed in {{< product >}} to your clipboard. Then run the command on your cluster node. + +9. When you finish running the command(s) on your Linux host(s), click **Done**. + +{{< result_create-cluster >}} diff --git a/content/rancher/tasks/global-configuration/_index.md b/content/rancher/tasks/global-configuration/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md b/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md new file mode 100644 index 00000000000..2e7fed216da --- /dev/null +++ b/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md @@ -0,0 +1,87 @@ +# Configuring User Authentication + +You have three options for user authentication in {{< product >}}: + +- **Active Directory**: Enterprises can use Active Directory (AD) for authentication, allowing users to sign in using their corporate credentials. + +- **GitHub**: Open source projects or organizations that use GitHub for source control may prefer that users sign in using their GitHub accounts. + +- **Basic Authentication**: If you don't want to use external authentication, you can always add users directly to {{< product >}}. We recommend using external authentication over basic authentication. + +## Configure an Authentication Method + +### To Configure Active Directory + +>**Prerequisites:** Create a service account in Active Directory with **read-only** access. {{< product >}} uses this account to verify group membership when a user makes a request using an API key. + +1. From the **Global** view, select **Security > Authentication** from the main menu. + +2. Select **Active Directory**. + +3. Complete the **Configure an Active Directory server** form. + + You may need to log in to your domain controller to find the information requested in the form. + + >**Using TLS?** + > + Make sure you have an [LDAP certificate installed](placeholder.md). + + >**User Search Base vs. Group Search Base** + > + >When configuring AD authentication, you must enter a search base for your users. This base allows Rancher to search for users that are in your Active Directory. + - If your users and groups are in the search base, complete only the User Search Base. + - If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required. + +4. If your Active Directory deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step. + +5. Enter your AD username and password in **Test and enable authentication** to confirm that Rancher is configured to use AD authentication. + +### To Configure GitHub + +1. From the **Global** view, select **Security > Authentication** from the main menu. + +2. Select **GitHub**. + +3. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration. + + >**What's an Authorization Callback URL?** + > + >The Authorization Callback URL is the URL where users to begin using your application (i.e. the splash screen). + + >When you use external authentication, sign on authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authorization completes successfully, the Authorization Callback URL is the location that the user reenters your application. + +4. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into {{< product >}}. + + >**Where do I find the Client ID and Client Secret?** + > + >From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. + +5. Click **Authenticate with GitHub**. + +6. Use the **Site Access** options to configure the scope of user authorization. + + - **Allow any valid Users** + + _Any_ GitHub user can access Rancher. We generally discourage use of this setting! + + - **Allow members of Clusters, Projects, plus Authorized Users and Organizations** + + Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher. + + - **Restrict access to only Authorized Users and Organizations** + + Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher. +
+7. Click **Save**. + +**Result:** + +- GitHub authentication is configured. +- You are signed into Rancher with your GitHub account. +- Your GitHub account is added to Rancher as an administrator. + +### To Configure Basic Authentication + +1. From the **Global** view, select **Users** from the main menu. + +2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done. diff --git a/content/rancher/tasks/global-configuration/pod-security-policies.md b/content/rancher/tasks/global-configuration/pod-security-policies.md new file mode 100644 index 00000000000..d88acf2da74 --- /dev/null +++ b/content/rancher/tasks/global-configuration/pod-security-policies.md @@ -0,0 +1,28 @@ +--- +tag: ["rancher", "pod security policies","security policies", "settings" ] +category: "rancher" +layout: list-docs +title: Adding Pod Security Policies +weight: 90 +--- + +# Adding Pod Security Policies + +Using {{< product >}}, you can create a pod security policy using our GUI rather than creating a .yaml file. + +1. From the **Global** view, select **Security** > **Pod Security Policies** from the main menu. Then click **Add Policy**. + + **Step Result:** The **Add Policy** form opens. + +2. Name the policy. +3. Complete each section of the form. Refer to the Kubernetes documentation linked below for more information on what each policy does. + + - Basic Policies + - Capability Policies + - Volume Policy + - Allowed Host Paths Policy + - FS Group Policy + - Host Ports Policy + - Run As User Policy + - SELinux Policy + - Supplemental Groups Policy diff --git a/content/rancher/tasks/global-configuration/roles.md b/content/rancher/tasks/global-configuration/roles.md new file mode 100644 index 00000000000..52b0abc0e42 --- /dev/null +++ b/content/rancher/tasks/global-configuration/roles.md @@ -0,0 +1,35 @@ +# Roles + +While _users_ determine who can log into Rancher, _roles_ determine which Kubernetes API endpoints and Rancher roles that a user can access after login. In other words, roles determine the user's _permissions_ when using Rancher. + +## Adding A Custom Role + +While Rancher comes out-of-the-box with a set of default user roles, you can also create custom roles to provide users with very specific permissions within Rancher. + +1. From the **Global** view, select **Security** > **Roles** from the main menu. + +2. Click **Add Role**. + +3. **Name** the role. + +4. Assign the role a **Context**. Context determines the scope of permissions assigned to the user. The contexts are: + + - **All** + + The user can use their assigned permissions regardless of context. The user's permissions are valid in all clusters and projects. + + - **Cluster** + + The user can use their assigned permissions within a selected cluster. + + - **Project** + + The user can use their assigned permissions within a selected project. + +5. Use the **Grant Resources** options to assign individual [Kubernetes API endpoints](https://kubernetes.io/docs/reference/) to the role. + + You can also choose the individual cURL methods (`Create`, `Delete`, `Get`, etc.) available for use with each endpoint you assign. + +6. Use the **Inherit from a Role** options to assign individual Rancher roles to your custom roles. + +7. Click **Create**. diff --git a/content/rancher/tasks/global-configuration/server-url.md b/content/rancher/tasks/global-configuration/server-url.md new file mode 100644 index 00000000000..bbf5789afbb --- /dev/null +++ b/content/rancher/tasks/global-configuration/server-url.md @@ -0,0 +1,17 @@ +--- +tag: ["rancher", "server url", "settings" ] +category: "rancher" +layout: list-docs +title: Updating the Server URL +weight: 90 +--- + +# Updating the {{< product >}} Server URL + +The first time that you log into {{< product >}}, the system prompts for the {{< product >}} Server URL, which is the IP address or host name that your Kubernetes nodes register with. + +If you need to update this URL, select **Settings** from the **Global** view. + +### When Should I Update the {{< product >}} Server URL? + +If URL of your {{< product >}} Server changes, you must update the {{< product >}} Server URL so that your nodes can continue communication with the {{< product >}} Server. diff --git a/content/rancher/tasks/miscellaneous/_index.md b/content/rancher/tasks/miscellaneous/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/pipelines/_index.md b/content/rancher/tasks/pipelines/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/projects/_index.md b/content/rancher/tasks/projects/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/users/_index.md b/content/rancher/tasks/users/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/workloads/_index.md b/content/rancher/tasks/workloads/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/layouts/shortcodes/prereq_cluster.html b/layouts/shortcodes/prereq_cluster.html new file mode 100644 index 00000000000..a9fa9fbe8a0 --- /dev/null +++ b/layouts/shortcodes/prereq_cluster.html @@ -0,0 +1,5 @@ +
+

+ Prerequisites: Review the [requirements](placeholder.md) for your Linux host. +

+
diff --git a/layouts/shortcodes/product.html b/layouts/shortcodes/product.html new file mode 100644 index 00000000000..e56e7808e0c --- /dev/null +++ b/layouts/shortcodes/product.html @@ -0,0 +1 @@ +Rancher diff --git a/layouts/shortcodes/result_create-cluster.html b/layouts/shortcodes/result_create-cluster.html new file mode 100644 index 00000000000..8aaada7a97c --- /dev/null +++ b/layouts/shortcodes/result_create-cluster.html @@ -0,0 +1,8 @@ +
+

Result:

+
    +
  • Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.
    • +
  • You can access your cluster after its state is updated to Active.
    • +
  • Active clusters are assigned a Project and Namespace, both of which are named Default.
    • +
+
diff --git a/layouts/shortcodes/step_create-cluster_cluster-options.html b/layouts/shortcodes/step_create-cluster_cluster-options.html new file mode 100644 index 00000000000..28064c50abd --- /dev/null +++ b/layouts/shortcodes/step_create-cluster_cluster-options.html @@ -0,0 +1 @@ +

Use Cluster Options to choose the version of Kubernetes installed on each cluster node, along with some other options for you cluster.

diff --git a/layouts/shortcodes/step_create-cluster_member-roles.html b/layouts/shortcodes/step_create-cluster_member-roles.html new file mode 100644 index 00000000000..6c4e3e3e45c --- /dev/null +++ b/layouts/shortcodes/step_create-cluster_member-roles.html @@ -0,0 +1,8 @@ +
+

Use Member Roles to configure user authorization for the cluster.

+
    +
  • Click Add Members to add users that can access the cluster.
    • +
  • Use the Role drop-down to set permissions for each user.
    • +
+
+
diff --git a/layouts/shortcodes/step_create-cluster_node-pools.html b/layouts/shortcodes/step_create-cluster_node-pools.html new file mode 100644 index 00000000000..7b3154d378f --- /dev/null +++ b/layouts/shortcodes/step_create-cluster_node-pools.html @@ -0,0 +1,10 @@ +

Add one or more Node Pools to your cluster. A node pool is a set of virtual machines configured identically to your Linux host. However, each node in the pool also has additional Kubernetes master and worker components installed.

+ +

+

Notes:

+
    +
  • After you create each node template, you can use it to create additional node pools.
    • +
  • Each Kubernetes role (i.e. etcd, Control, and Worker) must be filled. You can either apply all three roles to one pool or spread them around.
    • +
  • Ideally, you should have at least three etcd nodes so that your cluster can fail over to another if a etcd node goes down.
    • +
+
diff --git a/layouts/shortcodes/step_rancher-template.html b/layouts/shortcodes/step_rancher-template.html new file mode 100644 index 00000000000..d17c5be1616 --- /dev/null +++ b/layouts/shortcodes/step_rancher-template.html @@ -0,0 +1,14 @@ +

Complete the Rancher Template form to add metadata so that you can find your template in Rancher later.

+ diff --git a/layouts/shortcodes/version.html b/layouts/shortcodes/version.html new file mode 100644 index 00000000000..4149d033b05 --- /dev/null +++ b/layouts/shortcodes/version.html @@ -0,0 +1 @@ +v2.0 From 5ad9008500da635b570c21538a0826d5721bdb7e Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 18 Apr 2018 11:54:40 -0700 Subject: [PATCH 2/7] checking in skeleton for the install bucket so that contributors have some guidance about where to write their content. --- content/rancher/installation/_index.md | 3 +- content/rancher/installation/_no-internet.md | 0 .../installation/installation-scenarios.md | 0 .../installation/load-balancing-config.md | 18 +++++++++ content/rancher/installation/requirements.md | 25 ++++++++---- .../server-installation/_index.md | 11 ++++++ .../server-installation/multi-node-install.md | 14 +++++++ .../single-node-install.md | 18 +++++++++ content/rancher/installation/server-tags.md | 12 ++++++ content/rancher/installation/ssl-config.md | 26 +++++++++++++ .../clusters/creating-a-cluster/_index.md | 10 +++++ .../pod-security-policies.md | 39 ++++++++++++++----- 12 files changed, 159 insertions(+), 17 deletions(-) create mode 100644 content/rancher/installation/_no-internet.md create mode 100644 content/rancher/installation/installation-scenarios.md create mode 100644 content/rancher/installation/load-balancing-config.md create mode 100644 content/rancher/installation/server-installation/_index.md create mode 100644 content/rancher/installation/server-installation/multi-node-install.md create mode 100644 content/rancher/installation/server-installation/single-node-install.md create mode 100644 content/rancher/installation/server-tags.md create mode 100644 content/rancher/installation/ssl-config.md create mode 100644 content/rancher/tasks/clusters/creating-a-cluster/_index.md diff --git a/content/rancher/installation/_index.md b/content/rancher/installation/_index.md index 5ed56a7b24c..71dd85c24e7 100644 --- a/content/rancher/installation/_index.md +++ b/content/rancher/installation/_index.md @@ -6,5 +6,6 @@ weight: 100 --- -Notes: Installation Scenarios +# Installation Scenarios + A directory of install scenarios. Each scenario offers a synopsis. diff --git a/content/rancher/installation/_no-internet.md b/content/rancher/installation/_no-internet.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/installation/installation-scenarios.md b/content/rancher/installation/installation-scenarios.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/installation/load-balancing-config.md b/content/rancher/installation/load-balancing-config.md new file mode 100644 index 00000000000..4e6dafd07a2 --- /dev/null +++ b/content/rancher/installation/load-balancing-config.md @@ -0,0 +1,18 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Load Balancing Configuration + +## Option 1: Amazon ELB + +## Option 2: HAProxy + +## Option 3: NGINX diff --git a/content/rancher/installation/requirements.md b/content/rancher/installation/requirements.md index 9afea7f2a45..21d87dfdd24 100644 --- a/content/rancher/installation/requirements.md +++ b/content/rancher/installation/requirements.md @@ -1,13 +1,16 @@ # Rancher Requirements -#### Hardware Requirements +## Operating System Requirements + +- Operating System: Ubuntu 16.04 (64-bit) + +## Hardware Requirements - Memory: 4GB -#### Software requirements +## Software Requirements -- Operating System: Ubuntu 16.04 (64-bit) -- Software: Docker +- Docker **Supported Versions:** @@ -20,11 +23,11 @@ > * For Docker installation instructions, visit their [documentation](https://docs.docker.com/install/). > * Docker requirements apply to both your Linux host and your cluster nodes. -#### Port Requirements +## Port Requirements When provisioning your Linux host, open the ports listed below so that your master and worker nodes can communicate. -##### Master Nodes (etcd and controlplane nodes) +### Master Nodes (etcd and controlplane nodes) Protocol | Direction | Port Range | Purpose --|---|---|-- @@ -38,7 +41,7 @@ TCP | Inbound | 10251 | scheduler TCP | Inbound | 10252 | controller TCP | Inbound | 10256 | kubeproxy -##### Worker Nodes +### Worker Nodes Protocol | Direction | Port Range | Purpose --|---|---|-- @@ -48,3 +51,11 @@ TCP | Inbound | 443 | Canal TCP | Inbound | 10250 | kubelet API TCP | Inbound | 10256 | kubeproxy TCP | Inbound | 30000-32767 | NodePort Services + +## Additional Requirements + +### Non High Availability + +### High Availability + +### Optional: etcd diff --git a/content/rancher/installation/server-installation/_index.md b/content/rancher/installation/server-installation/_index.md new file mode 100644 index 00000000000..557d226341e --- /dev/null +++ b/content/rancher/installation/server-installation/_index.md @@ -0,0 +1,11 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "rancher" +--- + +# {{< product >}} Server Installation diff --git a/content/rancher/installation/server-installation/multi-node-install.md b/content/rancher/installation/server-installation/multi-node-install.md new file mode 100644 index 00000000000..df2464794e2 --- /dev/null +++ b/content/rancher/installation/server-installation/multi-node-install.md @@ -0,0 +1,14 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Multi-Node Installation + +## Part 1: Launch Using RKE diff --git a/content/rancher/installation/server-installation/single-node-install.md b/content/rancher/installation/server-installation/single-node-install.md new file mode 100644 index 00000000000..d7b0c19bb54 --- /dev/null +++ b/content/rancher/installation/server-installation/single-node-install.md @@ -0,0 +1,18 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Single Node Installation + +## Option 1: Single Container Install + +## Option 2: Single Container With External ETCD + +## Option 3: Local Cluster Install diff --git a/content/rancher/installation/server-tags.md b/content/rancher/installation/server-tags.md new file mode 100644 index 00000000000..2d816a2faf1 --- /dev/null +++ b/content/rancher/installation/server-tags.md @@ -0,0 +1,12 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Rancher Server Tags diff --git a/content/rancher/installation/ssl-config.md b/content/rancher/installation/ssl-config.md new file mode 100644 index 00000000000..da7b0105df1 --- /dev/null +++ b/content/rancher/installation/ssl-config.md @@ -0,0 +1,26 @@ +--- +title: "{{ replace .TranslationBaseName "-" " " | title }}" +date: {{ .Date }} +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# SSL Configuration + +## Before You Start: Choose a Certificate Host + +### On {{< product >}} + +### On Load Balancer + +## Option 1: Default Self-Signed Certificate + +## Option 2: Self-Provided Self-Signed Certificate + +## Option 3: LetsEncrypt Signed Certificate + +## Option 4: Certificate Authority Signed Certificate diff --git a/content/rancher/tasks/clusters/creating-a-cluster/_index.md b/content/rancher/tasks/clusters/creating-a-cluster/_index.md new file mode 100644 index 00000000000..f679977b2ab --- /dev/null +++ b/content/rancher/tasks/clusters/creating-a-cluster/_index.md @@ -0,0 +1,10 @@ +--- +tag: ["rancher", "pod security policies","security policies", "settings" ] +category: "rancher" +layout: list-docs +title: Creating a Cluster +weight: 90 +--- +# Creating a Cluster + +let's create clusters! diff --git a/content/rancher/tasks/global-configuration/pod-security-policies.md b/content/rancher/tasks/global-configuration/pod-security-policies.md index d88acf2da74..ef42aa83bd3 100644 --- a/content/rancher/tasks/global-configuration/pod-security-policies.md +++ b/content/rancher/tasks/global-configuration/pod-security-policies.md @@ -15,14 +15,35 @@ Using {{< product >}}, you can create a pod security policy using our GUI rather **Step Result:** The **Add Policy** form opens. 2. Name the policy. + 3. Complete each section of the form. Refer to the Kubernetes documentation linked below for more information on what each policy does. - - Basic Policies - - Capability Policies - - Volume Policy - - Allowed Host Paths Policy - - FS Group Policy - - Host Ports Policy - - Run As User Policy - - SELinux Policy - - Supplemental Groups Policy + - Basic Policies: + + - [Privilege Escalation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation) + - [Host Namespaces][2] + - [Read Only Root Filesystems][1] + + - [Capability Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#capabilities) + - [Volume Policy][1] + - [Allowed Host Paths Policy][1] + - [FS Group Policy][1] + - [Run As User Policy][1] + - [Host Ports Policy][2] + - [Run As User Policy][3] + - [SELinux Policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#selinux) + - [Supplemental Groups Policy][3] + +### What's Next? + +Now that you've created a Pod Security Policy, you can apply it to: + +- An existing cluster +- A brand new cluster. For more details, see [Creating a Cluster](../../clusters/creating-a-cluster/_index) + + + + +[1]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems +[2]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces +[3]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#users-and-groups From 5ce6c6015258fc9e4c5056b31e4e40f620047d61 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 18 Apr 2018 12:40:27 -0700 Subject: [PATCH 3/7] added note that aks is in beta. --- content/rancher/installation/server-installation/_index.md | 6 +++--- .../create-cluster-azure-container-service.md | 4 +++- layouts/shortcodes/beta-note_azure.html | 4 ++++ 3 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 layouts/shortcodes/beta-note_azure.html diff --git a/content/rancher/installation/server-installation/_index.md b/content/rancher/installation/server-installation/_index.md index 557d226341e..f413026489c 100644 --- a/content/rancher/installation/server-installation/_index.md +++ b/content/rancher/installation/server-installation/_index.md @@ -1,9 +1,9 @@ --- -title: "{{ replace .TranslationBaseName "-" " " | title }}" +title: "Rancher Server Installation" date: {{ .Date }} draft: true -tags: [ "tag", "tag", "tag", "tag" ] -layout: single-left +tags: [ "install" ] +layout: list categories: - "rancher" --- diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md index 71fa20d9ebb..4e1b465c493 100644 --- a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-azure-container-service.md @@ -1,7 +1,7 @@ --- tag: ["rancher", "cluster"] category: "rancher" -layout: list-docs +layout: single title: Azure Container Service weight: 30 --- @@ -10,6 +10,8 @@ weight: 30 You can use Rancher to create a cluster using Microsoft Azure Container Service. +{{< beta-note_azure >}} + 1. From the **Clusters** page, click **Add Cluster**. 2. Choose **Azure Container Service**. diff --git a/layouts/shortcodes/beta-note_azure.html b/layouts/shortcodes/beta-note_azure.html new file mode 100644 index 00000000000..61af0c6df35 --- /dev/null +++ b/layouts/shortcodes/beta-note_azure.html @@ -0,0 +1,4 @@ +
+ Note: +

As of {{< product >}} {{< version >}} GA, the Azure Container Service option is still in beta.

+
From 6639c041f1115a658c676fc2848374b7ddf184ef Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 18 Apr 2018 13:21:15 -0700 Subject: [PATCH 4/7] adding PR feedback --- content/rancher/concepts/users-and-roles.md | 2 +- content/rancher/installation/requirements.md | 9 ++++++--- .../clusters/creating-a-cluster/create-cluster-custom.md | 4 +++- .../authentication/configure-user-authentication.md | 6 +++--- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/content/rancher/concepts/users-and-roles.md b/content/rancher/concepts/users-and-roles.md index be5042709aa..5e327b599e7 100644 --- a/content/rancher/concepts/users-and-roles.md +++ b/content/rancher/concepts/users-and-roles.md @@ -1,6 +1,6 @@ # Users and Roles -Every user in {{< product >}} is assigned a _role_, which is a set of permissions that determine what Kubenetes API endpoints that the user can access. Let's use this metaphor: a user account is like getting access to an entire office building; however, the user's role determine what rooms the user can access within the building. +Every user in {{< product >}} is assigned a _role_, which is a set of permissions that determine what Kubernetes API endpoints that the user can access. Let's use this metaphor: a user account is like getting access to an entire office building; however, the user's role determine what rooms the user can access within the building. Within {{< product >}} there are two types of user roles: diff --git a/content/rancher/installation/requirements.md b/content/rancher/installation/requirements.md index 21d87dfdd24..ce9d18b4066 100644 --- a/content/rancher/installation/requirements.md +++ b/content/rancher/installation/requirements.md @@ -2,15 +2,18 @@ ## Operating System Requirements -- Operating System: Ubuntu 16.04 (64-bit) +- Ubuntu 16.04 (64-bit) +- Red Hat Enterprise Linux 7.5 (64-bit) +- RancherOS ## Hardware Requirements - Memory: 4GB -## Software Requirements -- Docker +## Software requirements + +- Software: Docker **Supported Versions:** diff --git a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md index 7d0da2efb9d..6c1e2f4c76e 100644 --- a/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md +++ b/content/rancher/tasks/clusters/creating-a-cluster/create-cluster-custom.md @@ -56,7 +56,9 @@ Use {{< product >}} to clone your Linux host and configure them as Kubernetes no > If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers). -8. **Optional**: Use **Labels** to add metadata so that you can find them later. +8. **Optional**: Add **Labels** to your cluster nodes to help schedule workloads later. + + [Kubernetes Documentation: Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) 9. Copy the command displayed on screen to your clipboard. diff --git a/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md b/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md index 2e7fed216da..2fa88595e20 100644 --- a/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md +++ b/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md @@ -1,12 +1,12 @@ # Configuring User Authentication -You have three options for user authentication in {{< product >}}: +You have three options for user authentication in {{< product >}}. We recommend using an external authentication method (i.e. Active Directory or GitHub) rather than local authentication. External authentication reduces upkeep of your users. - **Active Directory**: Enterprises can use Active Directory (AD) for authentication, allowing users to sign in using their corporate credentials. - **GitHub**: Open source projects or organizations that use GitHub for source control may prefer that users sign in using their GitHub accounts. -- **Basic Authentication**: If you don't want to use external authentication, you can always add users directly to {{< product >}}. We recommend using external authentication over basic authentication. +- **Local Authentication**: If you don't want to use external authentication, you can always add users directly to {{< product >}}. We recommend using external authentication over local authentication. ## Configure an Authentication Method @@ -80,7 +80,7 @@ You have three options for user authentication in {{< product >}}: - You are signed into Rancher with your GitHub account. - Your GitHub account is added to Rancher as an administrator. -### To Configure Basic Authentication +### To Configure Local Authentication 1. From the **Global** view, select **Users** from the main menu. From 09fbbac0dbd4244b2e261ac9691713e1994ff0af Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 18 Apr 2018 15:24:17 -0700 Subject: [PATCH 5/7] minor changes --- .../tasks/global-configuration/pod-security-policies.md | 8 +++++--- content/rancher/tasks/global-configuration/server-url.md | 3 ++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/content/rancher/tasks/global-configuration/pod-security-policies.md b/content/rancher/tasks/global-configuration/pod-security-policies.md index ef42aa83bd3..98a0e2f4a3f 100644 --- a/content/rancher/tasks/global-configuration/pod-security-policies.md +++ b/content/rancher/tasks/global-configuration/pod-security-policies.md @@ -1,14 +1,16 @@ --- tag: ["rancher", "pod security policies","security policies", "settings" ] category: "rancher" -layout: list-docs +layout: single title: Adding Pod Security Policies weight: 90 --- -# Adding Pod Security Policies +# Pod Security Policies -Using {{< product >}}, you can create a pod security policy using our GUI rather than creating a .yaml file. +## Adding Pod Security Policies + +Using {{< product >}}, you can create a Pod Security Policy using our GUI rather than creating a .yaml file. 1. From the **Global** view, select **Security** > **Pod Security Policies** from the main menu. Then click **Add Policy**. diff --git a/content/rancher/tasks/global-configuration/server-url.md b/content/rancher/tasks/global-configuration/server-url.md index bbf5789afbb..9624aeb7007 100644 --- a/content/rancher/tasks/global-configuration/server-url.md +++ b/content/rancher/tasks/global-configuration/server-url.md @@ -5,8 +5,9 @@ layout: list-docs title: Updating the Server URL weight: 90 --- +# Rancher Server URL -# Updating the {{< product >}} Server URL +## Updating the {{< product >}} Server URL The first time that you log into {{< product >}}, the system prompts for the {{< product >}} Server URL, which is the IP address or host name that your Kubernetes nodes register with. From 6e3162a64b381590264d207f02162ce21741cdbc Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Wed, 18 Apr 2018 18:58:03 -0700 Subject: [PATCH 6/7] adding global config/install docs. --- .../installation/load-balancing-config.md | 3 +- content/rancher/installation/requirements.md | 26 ++++-- .../server-installation/_index.md | 3 +- .../_index.md} | 3 +- .../single-node-install.md | 18 ---- .../single-node-installs/_index.md | 0 .../single-container-install.md | 28 ++++++ content/rancher/installation/server-tags.md | 11 ++- content/rancher/installation/ssl-config.md | 3 +- .../global-configuration/authentication.md | 0 .../configure-user-authentication.md | 87 ------------------- .../global-configuration/node-drivers.md | 19 ++++ layouts/shortcodes/beta-note_azure.html | 2 +- layouts/shortcodes/prereq_cluster.html | 2 +- layouts/shortcodes/prereq_install.html | 4 + 15 files changed, 86 insertions(+), 123 deletions(-) rename content/rancher/installation/server-installation/{multi-node-install.md => multi-node-installs/_index.md} (67%) delete mode 100644 content/rancher/installation/server-installation/single-node-install.md create mode 100644 content/rancher/installation/server-installation/single-node-installs/_index.md create mode 100644 content/rancher/installation/server-installation/single-node-installs/single-container-install.md create mode 100644 content/rancher/tasks/global-configuration/authentication.md delete mode 100644 content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md create mode 100644 content/rancher/tasks/global-configuration/node-drivers.md create mode 100644 layouts/shortcodes/prereq_install.html diff --git a/content/rancher/installation/load-balancing-config.md b/content/rancher/installation/load-balancing-config.md index 4e6dafd07a2..49fb0977020 100644 --- a/content/rancher/installation/load-balancing-config.md +++ b/content/rancher/installation/load-balancing-config.md @@ -1,6 +1,5 @@ --- -title: "{{ replace .TranslationBaseName "-" " " | title }}" -date: {{ .Date }} +title: Load Balancing Configuration draft: true tags: [ "tag", "tag", "tag", "tag" ] layout: single-left diff --git a/content/rancher/installation/requirements.md b/content/rancher/installation/requirements.md index ce9d18b4066..a53fb4ed728 100644 --- a/content/rancher/installation/requirements.md +++ b/content/rancher/installation/requirements.md @@ -1,5 +1,17 @@ +--- +title: Rancher Requirements +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + # Rancher Requirements +Before you install {{< product >}}, wrangle up these requirements. Yip! Yip! Yah! + ## Operating System Requirements - Ubuntu 16.04 (64-bit) @@ -11,9 +23,9 @@ - Memory: 4GB -## Software requirements +## Software Requirements -- Software: Docker +- Docker **Supported Versions:** @@ -35,25 +47,27 @@ When provisioning your Linux host, open the ports listed below so that your mast Protocol | Direction | Port Range | Purpose --|---|---|-- TCP | Inbound | 22 | SSH server -TCP | Inbound | 80 | Canal -TCP | Inbound | 443 | Canal +TCP | Inbound | 80 | ? +TCP | Inbound | 443 | ? TCP | Inbound | 6443 | Kubernetes API server TCP | Inbound | 2379-2380 | etcd server client API TCP | Inbound | 10250 | kubelet API TCP | Inbound | 10251 | scheduler TCP | Inbound | 10252 | controller TCP | Inbound | 10256 | kubeproxy +UDP | Inbound | 8472 | Canal ### Worker Nodes Protocol | Direction | Port Range | Purpose --|---|---|-- TCP | Inbound | 22 | SSH Server -TCP | Inbound | 80 | Canal -TCP | Inbound | 443 | Canal +TCP | Inbound | 80 | ? +TCP | Inbound | 443 | ? TCP | Inbound | 10250 | kubelet API TCP | Inbound | 10256 | kubeproxy TCP | Inbound | 30000-32767 | NodePort Services +UDP | Inbound | 8472 | Canal ## Additional Requirements diff --git a/content/rancher/installation/server-installation/_index.md b/content/rancher/installation/server-installation/_index.md index f413026489c..9a3ace6bf07 100644 --- a/content/rancher/installation/server-installation/_index.md +++ b/content/rancher/installation/server-installation/_index.md @@ -1,6 +1,5 @@ --- -title: "Rancher Server Installation" -date: {{ .Date }} +title: Rancher Server Installation draft: true tags: [ "install" ] layout: list diff --git a/content/rancher/installation/server-installation/multi-node-install.md b/content/rancher/installation/server-installation/multi-node-installs/_index.md similarity index 67% rename from content/rancher/installation/server-installation/multi-node-install.md rename to content/rancher/installation/server-installation/multi-node-installs/_index.md index df2464794e2..673507c7dca 100644 --- a/content/rancher/installation/server-installation/multi-node-install.md +++ b/content/rancher/installation/server-installation/multi-node-installs/_index.md @@ -1,6 +1,5 @@ --- -title: "{{ replace .TranslationBaseName "-" " " | title }}" -date: {{ .Date }} +title: Multi-Node Installation draft: true tags: [ "tag", "tag", "tag", "tag" ] layout: single-left diff --git a/content/rancher/installation/server-installation/single-node-install.md b/content/rancher/installation/server-installation/single-node-install.md deleted file mode 100644 index d7b0c19bb54..00000000000 --- a/content/rancher/installation/server-installation/single-node-install.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "{{ replace .TranslationBaseName "-" " " | title }}" -date: {{ .Date }} -draft: true -tags: [ "tag", "tag", "tag", "tag" ] -layout: single-left -categories: - - "" - - "" ---- - -# Single Node Installation - -## Option 1: Single Container Install - -## Option 2: Single Container With External ETCD - -## Option 3: Local Cluster Install diff --git a/content/rancher/installation/server-installation/single-node-installs/_index.md b/content/rancher/installation/server-installation/single-node-installs/_index.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/installation/server-installation/single-node-installs/single-container-install.md b/content/rancher/installation/server-installation/single-node-installs/single-container-install.md new file mode 100644 index 00000000000..3b6baf9b26b --- /dev/null +++ b/content/rancher/installation/server-installation/single-node-installs/single-container-install.md @@ -0,0 +1,28 @@ +--- +title: Single Node Installation +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- +# Single Container Install + +{{< prereq_install >}} + +## To Install Rancher Server + +Install {{< product >}} by connecting to your Linux host and running the single container installation command. + +1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. + +2. From your shell, enter the following command: + + ``` + $ sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/server + ``` + + >**Tip:** You can install different versions of {{< product >}} Server by using different [Server Tags](../../server-tags/). + +**Result:** Rancher is installed. diff --git a/content/rancher/installation/server-tags.md b/content/rancher/installation/server-tags.md index 2d816a2faf1..dcf6eec1330 100644 --- a/content/rancher/installation/server-tags.md +++ b/content/rancher/installation/server-tags.md @@ -1,6 +1,5 @@ --- -title: "{{ replace .TranslationBaseName "-" " " | title }}" -date: {{ .Date }} +title: Rancher Server Tags draft: true tags: [ "tag", "tag", "tag", "tag" ] layout: single-left @@ -10,3 +9,11 @@ categories: --- # Rancher Server Tags + +{{< product >}} Server has two different tags that you can use during installation. + +- `rancher/server:latest`: Our latest development builds. These builds are validated through our CI automation framework. These releases aren't for production environments. + +- `rancher/server:stable`: Our latest stable release builds. This tag is recommended for production. + +Please don't use any release with a `rc{n}` suffix. These rc builds are meant for the {{< product >}} team to test out builds. diff --git a/content/rancher/installation/ssl-config.md b/content/rancher/installation/ssl-config.md index da7b0105df1..695bbdd099e 100644 --- a/content/rancher/installation/ssl-config.md +++ b/content/rancher/installation/ssl-config.md @@ -1,6 +1,5 @@ --- -title: "{{ replace .TranslationBaseName "-" " " | title }}" -date: {{ .Date }} +title: SSL Configuration draft: true tags: [ "tag", "tag", "tag", "tag" ] layout: single-left diff --git a/content/rancher/tasks/global-configuration/authentication.md b/content/rancher/tasks/global-configuration/authentication.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md b/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md deleted file mode 100644 index 2fa88595e20..00000000000 --- a/content/rancher/tasks/global-configuration/authentication/configure-user-authentication.md +++ /dev/null @@ -1,87 +0,0 @@ -# Configuring User Authentication - -You have three options for user authentication in {{< product >}}. We recommend using an external authentication method (i.e. Active Directory or GitHub) rather than local authentication. External authentication reduces upkeep of your users. - -- **Active Directory**: Enterprises can use Active Directory (AD) for authentication, allowing users to sign in using their corporate credentials. - -- **GitHub**: Open source projects or organizations that use GitHub for source control may prefer that users sign in using their GitHub accounts. - -- **Local Authentication**: If you don't want to use external authentication, you can always add users directly to {{< product >}}. We recommend using external authentication over local authentication. - -## Configure an Authentication Method - -### To Configure Active Directory - ->**Prerequisites:** Create a service account in Active Directory with **read-only** access. {{< product >}} uses this account to verify group membership when a user makes a request using an API key. - -1. From the **Global** view, select **Security > Authentication** from the main menu. - -2. Select **Active Directory**. - -3. Complete the **Configure an Active Directory server** form. - - You may need to log in to your domain controller to find the information requested in the form. - - >**Using TLS?** - > - Make sure you have an [LDAP certificate installed](placeholder.md). - - >**User Search Base vs. Group Search Base** - > - >When configuring AD authentication, you must enter a search base for your users. This base allows Rancher to search for users that are in your Active Directory. - - If your users and groups are in the search base, complete only the User Search Base. - - If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required. - -4. If your Active Directory deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step. - -5. Enter your AD username and password in **Test and enable authentication** to confirm that Rancher is configured to use AD authentication. - -### To Configure GitHub - -1. From the **Global** view, select **Security > Authentication** from the main menu. - -2. Select **GitHub**. - -3. Follow the directions displayed to **Setup a GitHub Application**. Rancher redirects you to GitHub to complete registration. - - >**What's an Authorization Callback URL?** - > - >The Authorization Callback URL is the URL where users to begin using your application (i.e. the splash screen). - - >When you use external authentication, sign on authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authorization completes successfully, the Authorization Callback URL is the location that the user reenters your application. - -4. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into {{< product >}}. - - >**Where do I find the Client ID and Client Secret?** - > - >From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently. - -5. Click **Authenticate with GitHub**. - -6. Use the **Site Access** options to configure the scope of user authorization. - - - **Allow any valid Users** - - _Any_ GitHub user can access Rancher. We generally discourage use of this setting! - - - **Allow members of Clusters, Projects, plus Authorized Users and Organizations** - - Any GitHub user or group added as a **Cluster Member** or **Project Member** can log in to Rancher. Additionally, any GitHub user or group you add to the **Authorized Users and Organizations** list may log in to Rancher. - - - **Restrict access to only Authorized Users and Organizations** - - Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher. -
-7. Click **Save**. - -**Result:** - -- GitHub authentication is configured. -- You are signed into Rancher with your GitHub account. -- Your GitHub account is added to Rancher as an administrator. - -### To Configure Local Authentication - -1. From the **Global** view, select **Users** from the main menu. - -2. Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done. diff --git a/content/rancher/tasks/global-configuration/node-drivers.md b/content/rancher/tasks/global-configuration/node-drivers.md new file mode 100644 index 00000000000..30c306b72a6 --- /dev/null +++ b/content/rancher/tasks/global-configuration/node-drivers.md @@ -0,0 +1,19 @@ +# Node Drivers + +## Adding Custom Node Drivers + +If you create a cluster using a cloud provider that {{< product >}} doesn't support out-of-the-box, you may need to add the provider's drivers (or create them yourself) so that your nodes function properly. + +1. From the **Global** view, select **Node Drivers** from the main menu. + +2. Click **Add Node Driver**. + +3. Complete the **Add Node Driver** form. Then click **Create**. + +## Activating Node Drivers + +Using the **Custom** option, you can create a cluster using virtually any cloud provider. However, by default, {{< product >}} only activates drivers for the most popular cloud providers. If you want to use another provider, you'll have to activate their drivers. + +1. From the **Global** view, select **Node Drivers** from the main menu. + +2. Select the inactive drivers that you want to use. Then click **Add Node Driver**. diff --git a/layouts/shortcodes/beta-note_azure.html b/layouts/shortcodes/beta-note_azure.html index 61af0c6df35..45bc678961a 100644 --- a/layouts/shortcodes/beta-note_azure.html +++ b/layouts/shortcodes/beta-note_azure.html @@ -1,4 +1,4 @@
Note: -

As of {{< product >}} {{< version >}} GA, the Azure Container Service option is still in beta.

+

As of Rancher v2.0 GA, the Azure Container Service option is still in beta.

diff --git a/layouts/shortcodes/prereq_cluster.html b/layouts/shortcodes/prereq_cluster.html index a9fa9fbe8a0..cc9da6071ac 100644 --- a/layouts/shortcodes/prereq_cluster.html +++ b/layouts/shortcodes/prereq_cluster.html @@ -1,5 +1,5 @@

- Prerequisites: Review the [requirements](placeholder.md) for your Linux host. + Prerequisites: Review the Requirements for your Linux host.

diff --git a/layouts/shortcodes/prereq_install.html b/layouts/shortcodes/prereq_install.html new file mode 100644 index 00000000000..9941f520b66 --- /dev/null +++ b/layouts/shortcodes/prereq_install.html @@ -0,0 +1,4 @@ +
+

Before You Start

+

Provision a Linux host according to our Requirements.

+
From 1840e8c3fd86562c292e62e3efe986bc557cae44 Mon Sep 17 00:00:00 2001 From: Mark Bishop Date: Thu, 19 Apr 2018 15:00:40 -0700 Subject: [PATCH 7/7] requirement updates. --- content/rancher/concepts/authentication.md | 12 ++- content/rancher/installation/requirements.md | 78 --------------- .../installation/requirements/_index.md | 11 +++ .../requirements/node-requirements.md | 24 +++++ .../server-requirements-deployment-install.md | 25 +++++ .../requirements/server-requirements.md | 21 ++++ layouts/shortcodes/requirements_hardware.html | 6 ++ layouts/shortcodes/requirements_os.html | 8 ++ layouts/shortcodes/requirements_ports.html | 97 +++++++++++++++++++ layouts/shortcodes/requirements_software.html | 15 +++ 10 files changed, 215 insertions(+), 82 deletions(-) delete mode 100644 content/rancher/installation/requirements.md create mode 100644 content/rancher/installation/requirements/_index.md create mode 100644 content/rancher/installation/requirements/node-requirements.md create mode 100644 content/rancher/installation/requirements/server-requirements-deployment-install.md create mode 100644 content/rancher/installation/requirements/server-requirements.md create mode 100644 layouts/shortcodes/requirements_hardware.html create mode 100644 layouts/shortcodes/requirements_os.html create mode 100644 layouts/shortcodes/requirements_ports.html create mode 100644 layouts/shortcodes/requirements_software.html diff --git a/content/rancher/concepts/authentication.md b/content/rancher/concepts/authentication.md index 9cc8fc71317..cb202faef76 100644 --- a/content/rancher/concepts/authentication.md +++ b/content/rancher/concepts/authentication.md @@ -1,12 +1,16 @@ # Authentication -One of the key features that {{< product >}} adds to Kubernetes is enhanced user authentication. +One of the key features that {{< product >}} adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters. -By default, Kubernetes has some authentication shortcomings. Namely, users and groups are tied to the two scopes that Kubernetes uses to group resources: global and namespace. These scopes make it difficult to manage users and groups across different clusters and namespaces. Kubenetes allows integration with other authentication providers that work around these issues using plugins. However, this integration is not available to those leveraging cloud-based Kubenetes offerings such as Google Container Engine (GKE). +This centralized user authentication is accomplished using the {{< product >}} authentication proxy, which is installed with the rest of {{< product >}}. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account. -Rancher improves on Kubernetes authentication by integrating external authentication. Out-of-the-box, Rancher provides integration with the following authentication services: +## External vs. Local Authentication + +The {{< product >}} authentication proxy integrates with the following external authentication services. - Microsoft Active Directory - GitHub -## External vs. Local Authentication +However, {{< product >}} also provides local authentication. + +In most cases, you should use an external authentication service over local, as external authentication allows user management from a central location. However, you may want a few local authentication accounts for managing {{< product >}} under rare circumstances, such as if Active Directory is down. diff --git a/content/rancher/installation/requirements.md b/content/rancher/installation/requirements.md deleted file mode 100644 index a53fb4ed728..00000000000 --- a/content/rancher/installation/requirements.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Rancher Requirements -draft: true -tags: [ "tag", "tag", "tag", "tag" ] -layout: single-left -categories: - - "" - - "" ---- - -# Rancher Requirements - -Before you install {{< product >}}, wrangle up these requirements. Yip! Yip! Yah! - -## Operating System Requirements - -- Ubuntu 16.04 (64-bit) -- Red Hat Enterprise Linux 7.5 (64-bit) -- RancherOS - -## Hardware Requirements - -- Memory: 4GB - - -## Software Requirements - -- Docker - - **Supported Versions:** - - - `1.12.6` - - `1.13.1` - - `17.03.2` - - >**Notes:** - > - > * For Docker installation instructions, visit their [documentation](https://docs.docker.com/install/). - > * Docker requirements apply to both your Linux host and your cluster nodes. - -## Port Requirements - -When provisioning your Linux host, open the ports listed below so that your master and worker nodes can communicate. - -### Master Nodes (etcd and controlplane nodes) - -Protocol | Direction | Port Range | Purpose ---|---|---|-- -TCP | Inbound | 22 | SSH server -TCP | Inbound | 80 | ? -TCP | Inbound | 443 | ? -TCP | Inbound | 6443 | Kubernetes API server -TCP | Inbound | 2379-2380 | etcd server client API -TCP | Inbound | 10250 | kubelet API -TCP | Inbound | 10251 | scheduler -TCP | Inbound | 10252 | controller -TCP | Inbound | 10256 | kubeproxy -UDP | Inbound | 8472 | Canal - -### Worker Nodes - -Protocol | Direction | Port Range | Purpose ---|---|---|-- -TCP | Inbound | 22 | SSH Server -TCP | Inbound | 80 | ? -TCP | Inbound | 443 | ? -TCP | Inbound | 10250 | kubelet API -TCP | Inbound | 10256 | kubeproxy -TCP | Inbound | 30000-32767 | NodePort Services -UDP | Inbound | 8472 | Canal - -## Additional Requirements - -### Non High Availability - -### High Availability - -### Optional: etcd diff --git a/content/rancher/installation/requirements/_index.md b/content/rancher/installation/requirements/_index.md new file mode 100644 index 00000000000..8ac449884cb --- /dev/null +++ b/content/rancher/installation/requirements/_index.md @@ -0,0 +1,11 @@ +--- +title: Requirements +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Requirements diff --git a/content/rancher/installation/requirements/node-requirements.md b/content/rancher/installation/requirements/node-requirements.md new file mode 100644 index 00000000000..9ab7603439d --- /dev/null +++ b/content/rancher/installation/requirements/node-requirements.md @@ -0,0 +1,24 @@ +--- +title: Node Requirements +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- +# Node Requirements + +When creating or importing a Kubernetes cluster, make sure that each node meets to following requirements. + +{{< requirements_os >}} + +{{< requirements_hardware >}} + +{{< requirements_software >}} + +## Port Requirements + +Open the following ports on your cluster nodes so that they can communicate with each other. + +{{< requirements_ports >}} diff --git a/content/rancher/installation/requirements/server-requirements-deployment-install.md b/content/rancher/installation/requirements/server-requirements-deployment-install.md new file mode 100644 index 00000000000..c377cc55440 --- /dev/null +++ b/content/rancher/installation/requirements/server-requirements-deployment-install.md @@ -0,0 +1,25 @@ +--- +title: "Rancher Server Requirements: Existing Cluster Installs" +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Rancher Server Requirements: Existing Cluster Installs + +If you want to install {{< product >}} on a server in an existing Kubernetes cluster, you have some additional requirements that you need to account for. + +{{< requirements_os >}} + +{{< requirements_hardware >}} + +{{< requirements_software >}} + +## Port Requirements + +Open the following ports on your cluster nodes so that they can communicate with each other. + +{{< requirements_ports >}} diff --git a/content/rancher/installation/requirements/server-requirements.md b/content/rancher/installation/requirements/server-requirements.md new file mode 100644 index 00000000000..24abe03d630 --- /dev/null +++ b/content/rancher/installation/requirements/server-requirements.md @@ -0,0 +1,21 @@ +--- +title: Rancher Server Requirements +draft: true +tags: [ "tag", "tag", "tag", "tag" ] +layout: single-left +categories: + - "" + - "" +--- + +# Rancher Server Requirements + +Before you install {{< product >}}, wrangle up these requirements. Use these requirements for most {{< product >}} Server installation scenarios. Yip! Yip! Yah! + +>**Want to install {{< product >}} in an existing Kubernetes cluster?** +> +> Refer to [these requirements](server-requirements-deployment-install.md) instead. + +{{< requirements_os >}} + +{{< requirements_hardware >}} diff --git a/layouts/shortcodes/requirements_hardware.html b/layouts/shortcodes/requirements_hardware.html new file mode 100644 index 00000000000..bbcfaa73af2 --- /dev/null +++ b/layouts/shortcodes/requirements_hardware.html @@ -0,0 +1,6 @@ +
+

Hardware Requirements

+
    +
  • Memory: 4GB
    • +
+
diff --git a/layouts/shortcodes/requirements_os.html b/layouts/shortcodes/requirements_os.html new file mode 100644 index 00000000000..398033ad65d --- /dev/null +++ b/layouts/shortcodes/requirements_os.html @@ -0,0 +1,8 @@ +
+

Operating System Requirements

+
    +
  • Ubuntu 16.04 (64-bit)
    • +
  • Red Hat Enterprise Linux 7.5 (64-bit)
    • +
  • RancherOS 1.3.0 (64-bit)
    • +
+
diff --git a/layouts/shortcodes/requirements_ports.html b/layouts/shortcodes/requirements_ports.html new file mode 100644 index 00000000000..31136a09f7b --- /dev/null +++ b/layouts/shortcodes/requirements_ports.html @@ -0,0 +1,97 @@ +
+

Master Nodes (etcd and controlplane nodes)

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
protocoldirectionport rangepurpose
tcpinbound22ssh server
80?
443?
6443kubernetes api server
2379-2380etcd server client api
10250kubelet api
10251scheduler
10252controller
10256kubeproxy
udp8472canal
+

Worker Nodes

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
protocoldirectionport rangepurpose
tcpinbound22ssh server
80?
443?
10250kubelet api
10256kubeproxy
30000-32767nodeport services
udp8472canal
+
+
diff --git a/layouts/shortcodes/requirements_software.html b/layouts/shortcodes/requirements_software.html new file mode 100644 index 00000000000..ae6d4f989cd --- /dev/null +++ b/layouts/shortcodes/requirements_software.html @@ -0,0 +1,15 @@ +
+

Software Requestions

+ +