From b302f0ed2484c6e22db11084d942479a1ef57278 Mon Sep 17 00:00:00 2001 From: Denise Schannon Date: Tue, 17 Apr 2018 11:22:23 -0700 Subject: [PATCH] basis rancher folder struct --- .../r-five/_index.md | 0 .../r-five/five-placeholder.md | 0 .../r-four/_index.md | 0 .../r-four/four-placeholder.md | 0 .../r-one/_index.md | 0 .../r-one/a-placeholder.md | 0 .../r-one/b-placeholder.md | 0 .../r-one/c-placeholder.md | 0 .../r-one/one-nested/_index.md | 0 .../r-one/one-nested/two-placeholder.md | 0 .../r-one/one-placeholder.md | 0 .../r-one/three-placeholder.md | 0 .../r-one/two-placeholder.md | 0 .../r-three/_index.md | 0 .../r-three/three-placeholder.md | 0 .../r-two/_index.md | 0 .../r-two/two-placeholder.md | 0 content/rancher/_index.md | 9 + content/rancher/concepts/_index.md | 7 + content/rancher/installation/_index.md | 10 + content/rancher/quick-start-guide/_index.md | 402 ++++++++++++++++++ content/rancher/tasks/_index.md | 7 + content/rancher/upgrades/_index.md | 10 + 23 files changed, 445 insertions(+) rename content/{rancher => rancher-example}/r-five/_index.md (100%) rename content/{rancher => rancher-example}/r-five/five-placeholder.md (100%) rename content/{rancher => rancher-example}/r-four/_index.md (100%) rename content/{rancher => rancher-example}/r-four/four-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/_index.md (100%) rename content/{rancher => rancher-example}/r-one/a-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/b-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/c-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/one-nested/_index.md (100%) rename content/{rancher => rancher-example}/r-one/one-nested/two-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/one-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/three-placeholder.md (100%) rename content/{rancher => rancher-example}/r-one/two-placeholder.md (100%) rename content/{rancher => rancher-example}/r-three/_index.md (100%) rename content/{rancher => rancher-example}/r-three/three-placeholder.md (100%) rename content/{rancher => rancher-example}/r-two/_index.md (100%) rename content/{rancher => rancher-example}/r-two/two-placeholder.md (100%) create mode 100644 content/rancher/_index.md create mode 100644 content/rancher/concepts/_index.md create mode 100644 content/rancher/installation/_index.md create mode 100644 content/rancher/quick-start-guide/_index.md create mode 100644 content/rancher/tasks/_index.md create mode 100644 content/rancher/upgrades/_index.md diff --git a/content/rancher/r-five/_index.md b/content/rancher-example/r-five/_index.md similarity index 100% rename from content/rancher/r-five/_index.md rename to content/rancher-example/r-five/_index.md diff --git a/content/rancher/r-five/five-placeholder.md b/content/rancher-example/r-five/five-placeholder.md similarity index 100% rename from content/rancher/r-five/five-placeholder.md rename to content/rancher-example/r-five/five-placeholder.md diff --git a/content/rancher/r-four/_index.md b/content/rancher-example/r-four/_index.md similarity index 100% rename from content/rancher/r-four/_index.md rename to content/rancher-example/r-four/_index.md diff --git a/content/rancher/r-four/four-placeholder.md b/content/rancher-example/r-four/four-placeholder.md similarity index 100% rename from content/rancher/r-four/four-placeholder.md rename to content/rancher-example/r-four/four-placeholder.md diff --git a/content/rancher/r-one/_index.md b/content/rancher-example/r-one/_index.md similarity index 100% rename from content/rancher/r-one/_index.md rename to content/rancher-example/r-one/_index.md diff --git a/content/rancher/r-one/a-placeholder.md b/content/rancher-example/r-one/a-placeholder.md similarity index 100% rename from content/rancher/r-one/a-placeholder.md rename to content/rancher-example/r-one/a-placeholder.md diff --git a/content/rancher/r-one/b-placeholder.md b/content/rancher-example/r-one/b-placeholder.md similarity index 100% rename from content/rancher/r-one/b-placeholder.md rename to content/rancher-example/r-one/b-placeholder.md diff --git a/content/rancher/r-one/c-placeholder.md b/content/rancher-example/r-one/c-placeholder.md similarity index 100% rename from content/rancher/r-one/c-placeholder.md rename to content/rancher-example/r-one/c-placeholder.md diff --git a/content/rancher/r-one/one-nested/_index.md b/content/rancher-example/r-one/one-nested/_index.md similarity index 100% rename from content/rancher/r-one/one-nested/_index.md rename to content/rancher-example/r-one/one-nested/_index.md diff --git a/content/rancher/r-one/one-nested/two-placeholder.md b/content/rancher-example/r-one/one-nested/two-placeholder.md similarity index 100% rename from content/rancher/r-one/one-nested/two-placeholder.md rename to content/rancher-example/r-one/one-nested/two-placeholder.md diff --git a/content/rancher/r-one/one-placeholder.md b/content/rancher-example/r-one/one-placeholder.md similarity index 100% rename from content/rancher/r-one/one-placeholder.md rename to content/rancher-example/r-one/one-placeholder.md diff --git a/content/rancher/r-one/three-placeholder.md b/content/rancher-example/r-one/three-placeholder.md similarity index 100% rename from content/rancher/r-one/three-placeholder.md rename to content/rancher-example/r-one/three-placeholder.md diff --git a/content/rancher/r-one/two-placeholder.md b/content/rancher-example/r-one/two-placeholder.md similarity index 100% rename from content/rancher/r-one/two-placeholder.md rename to content/rancher-example/r-one/two-placeholder.md diff --git a/content/rancher/r-three/_index.md b/content/rancher-example/r-three/_index.md similarity index 100% rename from content/rancher/r-three/_index.md rename to content/rancher-example/r-three/_index.md diff --git a/content/rancher/r-three/three-placeholder.md b/content/rancher-example/r-three/three-placeholder.md similarity index 100% rename from content/rancher/r-three/three-placeholder.md rename to content/rancher-example/r-three/three-placeholder.md diff --git a/content/rancher/r-two/_index.md b/content/rancher-example/r-two/_index.md similarity index 100% rename from content/rancher/r-two/_index.md rename to content/rancher-example/r-two/_index.md diff --git a/content/rancher/r-two/two-placeholder.md b/content/rancher-example/r-two/two-placeholder.md similarity index 100% rename from content/rancher/r-two/two-placeholder.md rename to content/rancher-example/r-two/two-placeholder.md diff --git a/content/rancher/_index.md b/content/rancher/_index.md new file mode 100644 index 00000000000..5e5d21864b9 --- /dev/null +++ b/content/rancher/_index.md @@ -0,0 +1,9 @@ +--- + tag: ["rancher", "overview"] + category: "rancher" + layout: list-docs + title: Rancher 2.0 Documentation + weight: 1 +--- + +Rancher 2.0 diff --git a/content/rancher/concepts/_index.md b/content/rancher/concepts/_index.md new file mode 100644 index 00000000000..3db1716481e --- /dev/null +++ b/content/rancher/concepts/_index.md @@ -0,0 +1,7 @@ +--- + tag: ["rancher", "concepts"] + category: "rancher" + layout: list-docs + title: Rancher Overview + weight: 300 +--- diff --git a/content/rancher/installation/_index.md b/content/rancher/installation/_index.md new file mode 100644 index 00000000000..5ed56a7b24c --- /dev/null +++ b/content/rancher/installation/_index.md @@ -0,0 +1,10 @@ +--- + tag: ["rancher", "installation"] + category: "rancher" + layout: list-docs + title: Installation + weight: 100 +--- + +Notes: Installation Scenarios +A directory of install scenarios. Each scenario offers a synopsis. diff --git a/content/rancher/quick-start-guide/_index.md b/content/rancher/quick-start-guide/_index.md new file mode 100644 index 00000000000..16783d989c0 --- /dev/null +++ b/content/rancher/quick-start-guide/_index.md @@ -0,0 +1,402 @@ +--- +tag: ["rancher", "quick start"] +category: "rancher" +layout: list-docs +title: Quick Start Guide +weight: 2 +--- + +Quick Start Guide +--- + +This tutorial walks you through installation of Rancher v2.0, creation of your first cluster, and deployment of an application. + +>**Note:** Upgrades are not supported during the Rancher v2.0 beta. + +### Objectives + +Creation of your first cluster is a multi-stage process that we've broken into different tasks. + +1. [Review Requirements](#host-and-node-requirements) + + Before you do anything, review the requirements. + +2. [Prepare a Linux Host](#prepare-a-linux-host) + + First, you need to provision a Linux host. + +3. [Install Rancher](#install-rancher) + + Run the Docker command for installing Rancher. + +4. [Log In](#log-in) + + Browse to your Linux host to access the Rancher UI. + +5. [Create a Cluster](#create-a-cluster) + + Use Rancher to create your first cluster. + +6. [Deploy a Workload](#deploy-a-workload) + + Create a workload so that Kubernetes can distribute an application and its dependencies among your nodes. + +7. [View Your Application](#view-your-application) + + When your workload finishes deployment, browse to your application to make sure it works. + +8. [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. + +### Host and Node 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 + +### 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. + +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:preview + ``` + + >**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. + +1. Open a web browser and enter the IP address of your host: + + `https://` + + 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) + + +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. + + ![login](../../../../img/rancher/server-url.png) + +### Create a 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. + +1. Click **+ Add Cluster**. + + ![add cluster](../../../../img/rancher/click-add-cluster.png) + + **Step Result:** The **Add Cluster** page opens. + +2. From the **Add Cluster** menu, choose a service or source from which to create your first cluster. + + * 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**. + + > **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. + +3. Enter a **Cluster Name**. No spaces allowed. + + > **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) + +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`. + +### 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. + +1. From the **Clusters** page, open the cluster that you just created. + +2. From the main menu of the **Dashboard**, select **Projects**. + +3. Open the **Default** project. + +4. Click **+ Deploy**. + + ![click-deploy](../../../../img/rancher/click-deploy.png) + + **Step Result:** The **Deploy Workload** page opens. + +5. Enter a **Name** for your workload. No spaces allowed. + +6. From the **Docker Image** field, enter the name of an image hosted on [Docker Hub](https://hub.docker.com/explore/). + + 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. + + ![enter-docker-image](../../../../img/rancher/enter-docker-image.png) + +7. From the **Container Port** field, enter `80`. + + >**Note:** During Rancher v2.0 beta, only port 80 is supported. Other ports will be supported at GA. + +8. Leave the remaining options on their default setting. We'll tell you about them later. + +9. Click **Launch**. + +**Result:** + +* Your workload is deployed. This process might take a few minutes to complete. +* When your workload completes deployment, it's assigned a state of **Active**. You can view this status from the project's **Workloads** page. + +### View Your Application + +When your workload completes deployment, browse to your application to confirm that it's 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). + + diff --git a/content/rancher/tasks/_index.md b/content/rancher/tasks/_index.md new file mode 100644 index 00000000000..dcae3909c02 --- /dev/null +++ b/content/rancher/tasks/_index.md @@ -0,0 +1,7 @@ +--- + tag: ["rancher", "tasks"] + category: "rancher" + layout: list-docs + title: Tasks + weight: 400 +--- diff --git a/content/rancher/upgrades/_index.md b/content/rancher/upgrades/_index.md new file mode 100644 index 00000000000..0d1c3ebebea --- /dev/null +++ b/content/rancher/upgrades/_index.md @@ -0,0 +1,10 @@ +--- + tag: ["rancher", "upgrades"] + category: "rancher" + layout: list-docs + title: Upgrade Scenarios + weight: 200 +--- + +Notes: 1. Upgrade Scenarios +A list of upgrade scenarios. Each scenario offers a synopsis.