Apply commits 50a118c4..133007cd from master

This commit is contained in:
Billy Tat
2022-07-12 13:14:04 -07:00
parent 4217b278b8
commit c804a16d64
26 changed files with 347 additions and 221 deletions
@@ -0,0 +1,124 @@
---
title: Installing Rancher on Azure Kubernetes Service
shortTitle: AKS
weight: 3
---
This page covers how to install Rancher on Microsoft's Azure Kubernetes Service (AKS).
The guide uses command line tools to provision an AKS cluster with an ingress. If you prefer to provision your cluster using the Azure portal, refer to the [official documentation](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal).
If you already have an AKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart)
# Prerequisites
:::caution
Deploying to Microsoft Azure will incur charges.
:::
- [Microsoft Azure Account](https://azure.microsoft.com/en-us/free/): A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes.
- [Microsoft Azure Subscription](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription#create-a-subscription-in-the-azure-portal): Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet.
- [Micsoroft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant): Use this link and follow instructions to create a Microsoft Azure tenant.
- Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to [this section]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/#rke-and-hosted-kubernetes)
- When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on [Azure load balancer limitations](https://docs.microsoft.com/en-us/azure/load-balancer/components#limitations).
# 1. Prepare your Workstation
Install the following command line tools on your workstation:
- The Azure CLI, **az:** For help, refer to these [installation steps.](https://docs.microsoft.com/en-us/cli/azure/)
- **kubectl:** For help, refer to these [installation steps.](https://kubernetes.io/docs/tasks/tools/#kubectl)
- **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/)
# 2. Create a Resource Group
After installing the CLI, you will need to log in with your Azure account.
```
az login
```
Create a [resource group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal) to hold all relevant resources for your cluster. Use a location that applies to your use case.
```
az group create --name rancher-rg --location eastus
```
# 3. Create the AKS Cluster
To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
**Note:** If the version of Kubernetes is updated to v1.22 or later, the version of ingress-nginx would also need to be [updated](https://kubernetes.github.io/ingress-nginx/#faq-migration-to-apiversion-networkingk8siov1).
```
az aks create \
--resource-group rancher-rg \
--name rancher-server \
--kubernetes-version <VERSION> \
--node-count 3 \
--node-vm-size Standard_D2_v3
```
The cluster will take some time to be deployed.
# 4. Get Access Credentials
After the cluster is deployed, get the access credentials.
```
az aks get-credentials --resource-group rancher-rg --name rancher-server
```
This command merges your cluster's credentials into the existing kubeconfig and allows `kubectl` to interact with the cluster.
# 5. Install an Ingress
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription.
The following command installs an `nginx-ingress-controller` with a Kubernetes load balancer service.
```
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--set controller.service.type=LoadBalancer \
--version 3.12.0 \
--create-namespace
```
# 6. Get Load Balancer IP
To get the address of the load balancer, run:
```
kubectl get service ingress-nginx-controller --namespace=ingress-nginx
```
The result should look similar to the following:
```
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
AGE
ingress-nginx-controller LoadBalancer 10.0.116.18 40.31.180.83 80:31229/TCP,443:31050/TCP
67s
```
Save the `EXTERNAL-IP`.
# 7. Set up DNS
External traffic to the Rancher server will need to be directed at the load balancer you created.
Set up a DNS to point at the `EXTERNAL-IP` that you saved. This DNS will be used as the Rancher server URL.
There are many valid ways to set up the DNS. For help, refer to the [Azure DNS documentation](https://docs.microsoft.com/en-us/azure/dns/)
# 8. Install the Rancher Helm Chart
Next, install the Rancher Helm chart by following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution.
Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`.
@@ -0,0 +1,166 @@
---
title: Installing Rancher on Amazon EKS
shortTitle: Amazon EKS
weight: 3
---
This page covers two ways to install Rancher on EKS.
The first is a guide for deploying the Rancher server on an EKS cluster using CloudFormation. This guide was created in collaboration with Amazon Web Services to show how to deploy Rancher following best practices.
The second is a guide for installing an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.
If you already have an EKS Kubernetes cluster, skip to the step about [installing an ingress.](#5-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart)
- [Automated Quickstart using AWS Best Practices](#automated-quickstart-using-aws-best-practices)
- [Creating an EKS Cluster for the Rancher Server](#creating-an-eks-cluster-for-the-rancher-server)
# Automated Quickstart using AWS Best Practices
Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS cluster following AWS best practices. The deployment guide is [here.](https://aws-quickstart.github.io/quickstart-eks-rancher/)
The quick start guide provides three options for deploying Rancher on EKS:
- **Deploy Rancher into a new VPC and new Amazon EKS cluster**. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, Amazon EKS cluster, and other infrastructure components. It then deploys Rancher into this new EKS cluster.
- **Deploy Rancher into an existing VPC and a new Amazon EKS cluster**. This option provisions Rancher in your existing AWS infrastructure.
- **Deploy Rancher into an existing VPC and existing Amazon EKS cluster**. This option provisions Rancher in your existing AWS infrastructure.
Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon EKS cluster using default parameters builds the following Rancher environment in the AWS Cloud:
- A highly available architecture that spans three Availability Zones.*
- A VPC configured with public and private subnets, according to AWS best practices, to provide you with your own virtual network on AWS.*
- In the public subnets:
- Managed network address translation (NAT) gateways to allow outbound internet access for resources.*
- Linux bastion hosts in an Auto Scaling group to allow inbound Secure Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets.*
- In the private subnets:
- Kubernetes nodes in an Auto Scaling group.*
- A Network Load Balancer (not shown) for accessing the Rancher console.
- Rancher deployment using AWS Systems Manager automation.
- Amazon EKS service for the EKS cluster, which provides the Kubernetes control plane.*
- An Amazon Route 53 DNS record for accessing the Rancher deployment.
\* The CloudFormation template that deploys the Quick Start into an existing Amazon EKS cluster skips the components marked by asterisks and prompts you for your existing VPC configuration.
# Creating an EKS Cluster for the Rancher Server
In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.
:::note Prerequisites:
- You should already have an AWS account.
- It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface.
- The IAM user needs the minimum IAM policies described in the official [eksctl documentation.](https://eksctl.io/usage/minimum-iam-policies/)
:::
### 1. Prepare your Workstation
Install the following command line tools on your workstation:
- **The AWS CLI v2:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
- **eksctl:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html)
- **kubectl:** For help, refer to these [installation steps.](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html)
- **helm:** For help, refer to these [installation steps.](https://helm.sh/docs/intro/install/)
### 2. Configure the AWS CLI
To configure the AWS CLI, run the following command:
```
aws configure
```
Then enter the following values:
| Value | Description |
|-------|-------------|
| AWS Access Key ID | The access key credential for the IAM user with EKS permissions. |
| AWS Secret Access Key | The secret key credential for the IAM user with EKS permissions. |
| Default region name | An [AWS region](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html#Concepts.RegionsAndAvailabilityZones.Regions) where the cluster nodes will be located. |
| Default output format | Enter `json`. |
### 3. Create the EKS Cluster
To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
```
eksctl create cluster \
--name rancher-server \
--version 1.20 \
--region us-west-2 \
--nodegroup-name ranchernodes \
--nodes 3 \
--nodes-min 1 \
--nodes-max 4 \
--managed
```
The cluster will take some time to be deployed with CloudFormation.
### 4. Test the Cluster
To test the cluster, run:
```
eksctl get cluster
```
The result should look like the following:
```
eksctl get cluster
2021-03-18 15:09:35 [ℹ] eksctl version 0.40.0
2021-03-18 15:09:35 [ℹ] using region us-west-2
NAME REGION EKSCTL CREATED
rancher-server-cluster us-west-2 True
```
### 5. Install an Ingress
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.
The following command installs an `nginx-ingress-controller` with a LoadBalancer service. This will result in an ELB (Elastic Load Balancer) in front of NGINX:
```
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--set controller.service.type=LoadBalancer \
--version 3.12.0 \
--create-namespace
```
### 6. Get Load Balancer IP
To get the address of the load balancer, run:
```
kubectl get service ingress-nginx-controller --namespace=ingress-nginx
```
The result should look similar to the following:
```
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)
AGE
ingress-nginx-controller LoadBalancer 10.100.90.18 a904a952c73bf4f668a17c46ac7c56ab-962521486.us-west-2.elb.amazonaws.com 80:31229/TCP,443:31050/TCP
27m
```
Save the `EXTERNAL-IP`.
### 7. Set up DNS
External traffic to the Rancher server will need to be directed at the load balancer you created.
Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.
There are many valid ways to set up the DNS. For help, refer to the AWS documentation on [routing traffic to an ELB load balancer.](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer.html)
### 8. Install the Rancher Helm Chart
Next, install the Rancher Helm chart by following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution.
Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`.
@@ -0,0 +1,182 @@
---
title: Installing Rancher on a Google Kubernetes Engine Cluster
shortTitle: GKE
weight: 3
---
In this section, you'll learn how to install Rancher using Google Kubernetes Engine.
If you already have a GKE Kubernetes cluster, skip to the step about [installing an ingress.](#7-install-an-ingress) Then install the Rancher Helm chart following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart)
# Prerequisites
- You will need a Google account.
- You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit [General guide to the console.](https://support.google.com/cloud/answer/3465889?hl=en&ref_topic=3340599)
- You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to [this section.]({{<baseurl>}}/rancher/v2.6/en/installation/requirements/#rke-and-hosted-kubernetes)
# 1. Enable the Kubernetes Engine API
Take the following steps to enable the Kubernetes Engine API:
1. Visit the [Kubernetes Engine page](https://console.cloud.google.com/projectselector/kubernetes?_ga=2.169595943.767329331.1617810440-856599067.1617343886) in the Google Cloud Console.
1. Create or select a project.
1. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes.
1. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the [Google Cloud documentation.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
# 2. Open the Cloud Shell
Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the `gcloud` command-line tool and kubectl command-line tool. The `gcloud` tool provides the primary command-line interface for Google Cloud, and `kubectl` provides the primary command-line interface for running commands against Kubernetes clusters.
The following sections describe how to launch the cloud shell from the Google Cloud Console or from your local workstation.
### Cloud Shell
To launch the shell from the [Google Cloud Console,](https://console.cloud.google.com) go to the upper-right corner of the console and click the terminal button. When hovering over the button, it is labeled **Activate Cloud Shell**.
### Local Shell
To install `gcloud` and `kubectl`, perform the following steps:
1. Install the Cloud SDK by following [these steps.](https://cloud.google.com/sdk/docs/install) The Cloud SDK includes the `gcloud` command-line tool. The steps vary based on your OS.
1. After installing Cloud SDK, install the `kubectl` command-line tool by running the following command:
```
gcloud components install kubectl
```
In a later step, `kubectl` will be configured to use the new GKE cluster.
1. [Install Helm 3](https://helm.sh/docs/intro/install/) if it is not already installed.
1. Enable Helm experimental [support for OCI images](https://github.com/helm/community/blob/master/hips/hip-0006.md) with the `HELM_EXPERIMENTAL_OCI` variable. Add the following line to `~/.bashrc` (or `~/.bash_profile` in macOS, or wherever your shell stores environment variables):
```
export HELM_EXPERIMENTAL_OCI=1
```
1. Run the following command to load your updated `.bashrc` file:
```
source ~/.bashrc
```
If you are running macOS, use this command:
```
source ~/.bash_profile
```
# 3. Configure the gcloud CLI
Set up default gcloud settings using one of the following methods:
- Using gcloud init, if you want to be walked through setting defaults.
- Using gcloud config, to individually set your project ID, zone, and region.
{{% tabs %}}
{{% tab "Using gcloud init" %}}
1. Run gcloud init and follow the directions:
```
gcloud init
```
If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:
```
gcloud init --console-only
```
2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created.
{{% /tab %}}
{{% tab "Using gcloud config" %}}
{{% /tab %}}
{{% /tabs %}}
# 4. Confirm that gcloud is configured correctly
Run:
```
gcloud config list
```
The output should resemble the following:
```
[compute]
region = us-west1 # Your chosen region
zone = us-west1-b # Your chosen zone
[core]
account = <Your email>
disable_usage_reporting = True
project = <Your project ID>
Your active configuration is: [default]
```
# 5. Create a GKE Cluster
The following command creates a three-node cluster.
Replace `cluster-name` with the name of your new cluster.
When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
```
gcloud container clusters create cluster-name --num-nodes=3 --cluster-version=1.20.8-gke.900
```
# 6. Get Authentication Credentials
After creating your cluster, you need to get authentication credentials to interact with the cluster:
```
gcloud container clusters get-credentials cluster-name
```
This command configures `kubectl` to use the cluster you created.
# 7. Install an Ingress
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.
The following command installs an `nginx-ingress-controller` with a LoadBalancer service:
```
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--set controller.service.type=LoadBalancer \
--version 3.12.0 \
--create-namespace
```
# 8. Get the Load Balancer IP
To get the address of the load balancer, run:
```
kubectl get service ingress-nginx-controller --namespace=ingress-nginx
```
The result should look similar to the following:
```
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ingress-nginx-controller LoadBalancer 10.3.244.156 35.233.206.34 80:31876/TCP,443:32497/TCP 81s
```
Save the `EXTERNAL-IP`.
# 9. Set up DNS
External traffic to the Rancher server will need to be directed at the load balancer you created.
Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.
There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about [managing DNS records.](https://cloud.google.com/dns/docs/records)
# 10. Install the Rancher Helm chart
Next, install the Rancher Helm chart by following the instructions on [this page.]({{<baseurl>}}/rancher/v2.6/en/installation/install-rancher-on-k8s/#install-the-rancher-helm-chart) The Helm instructions are the same for installing Rancher on any Kubernetes distribution.
Use the DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is `rancher.my.org`, you could run the Helm installation command with the option `--set hostname=rancher.my.org`.