Use Rancher to create a Kubernetes cluster in Amazon EC2.

Prerequisites

Creating an EC2 Cluster

The steps to create a cluster differ based on your Rancher version.

  1. Create your cloud credentials
  2. Create a node template with your cloud credentials and information from EC2
  3. Create a cluster with node pools using the node template

1. Create your cloud credentials

  1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
  2. Click Add Cloud Credential.
  3. Enter a name for the cloud credential.
  4. In the Cloud Credential Type field, select Amazon.
  5. In the Region field, select the AWS region where your cluster nodes will be located.
  6. Enter your AWS EC2 Access Key and Secret Key.
  7. Click Create.

Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

2. Create a node template with your cloud credentials and information from EC2

Complete each of the following forms using information available from the EC2 Management Console.

  1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
  2. Click Add Template.
  3. In the Region field, select the same region that you used when creating your cloud credentials.
  4. In the Cloud Credentials field, select your newly created cloud credentials.
  5. Click Next: Authenticate & configure nodes.
  6. Choose an availability zone and network settings for your cluster. Click Next: Select a Security Group.
  7. Choose the default security group or configure a security group. Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group. Then click Next: Set Instance options.
  8. Configure the instances that will be created. Make sure you configure the correct SSH User for the configured AMI.

If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a Kubernetes Cloud Provider, you will need an additional permission in your policy. See Example IAM policy with PassRole for an example policy.

Optional: In the Engine Options section of the node template, you can configure the Docker daemon. You may want to specify the docker version or a Docker registry mirror.

3. Create a cluster with node pools using the node template

Add one or more node pools to your cluster.

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

Notes:

  • Each node role (i.e. etcd, Control Plane, and Worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.
  • The recommended setup is to have a node pool with the etcd node role and a count of three, a node pool with the Control Plane node role and a count of at least two, and a node pool with the Worker node role and a count of at least two. Regarding the etcd node role, refer to the etcd Admin Guide.
  1. From the Clusters page, click Add Cluster.

  2. Choose Amazon EC2.

  3. Enter a Cluster Name.

  4. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created.

  5. Click Add Member to add users that can access the cluster.

  6. Use the Role drop-down to set permissions for each user.

  7. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. Refer to Selecting Cloud Providers to configure the Kubernetes Cloud Provider.

  8. 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 two Projects, Default (containing the namespace default) and System (containing the namespaces cattle-system,ingress-nginx,kube-public and kube-system, if present).

  1. From the Clusters page, click Add Cluster.

  2. Choose Amazon EC2.

  3. Enter a Cluster Name.

  4. Use Member Roles to configure user authorization for the cluster.

    • Click Add Member to add users that can access the cluster.
    • Use the Role drop-down to set permissions for each user.

  5. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. Refer to Selecting Cloud Providers to configure the Kubernetes Cloud Provider.

  6. Add one or more node pools to your cluster.

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

Notes:

  • Each node role (i.e. etcd, Control Plane, and Worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.
  • The recommended setup is to have a node pool with the etcd node role and a count of three, a node pool with the Control Plane node role and a count of at least two, and a node pool with the Worker node role and a count of at least two. Regarding the etcd node role, refer to the etcd Admin Guide.
  1. Click Add Node Template.

  2. Complete each of the following forms using information available from the EC2 Management Console.

    • Account Access is where you configure the region of the nodes, and the credentials (Access Key and Secret Key) used to create the machine. See Prerequisites how to create the Access Key and Secret Key and the needed permissions.
    • Zone and Network configures the availability zone and network settings for your cluster.
    • Security Groups creates or configures the Security Groups applied to your nodes. Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group.
    • Instance configures the instances that will be created. Make sure you configure the correct SSH User for the configured AMI.

      If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a Kubernetes Cloud Provider, you will need an additional permission in your policy. See Example IAM policy with PassRole for an example policy.
  3. The Docker daemon configuration options include:

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

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

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

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

  4. Click Create.

  5. Optional: Add additional node pools.

  6. Review your cluster settings to confirm they are correct. Then 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 two Projects, Default (containing the namespace default) and System (containing the namespaces cattle-system,ingress-nginx,kube-public and kube-system, if present).

Optional Next Steps

After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

  • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
  • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

Example IAM Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:Describe*",
                "ec2:ImportKeyPair",
                "ec2:CreateKeyPair",
                "ec2:CreateSecurityGroup",
                "ec2:CreateTags",
                "ec2:DeleteKeyPair"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "ec2:RunInstances"
            ],
            "Resource": [
                "arn:aws:ec2:REGION::image/ami-*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*"
            ]
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": [
                "ec2:RebootInstances",
                "ec2:TerminateInstances",
                "ec2:StartInstances",
                "ec2:StopInstances"
            ],
            "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
        }
    ]
}

Example IAM Policy with PassRole

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ec2:AuthorizeSecurityGroupIngress",
                "ec2:Describe*",
                "ec2:ImportKeyPair",
                "ec2:CreateKeyPair",
                "ec2:CreateSecurityGroup",
                "ec2:CreateTags",
                "ec2:DeleteKeyPair"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole",
                "ec2:RunInstances"
            ],
            "Resource": [
                "arn:aws:ec2:REGION::image/ami-*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*",
                "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME"
            ]
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": [
                "ec2:RebootInstances",
                "ec2:TerminateInstances",
                "ec2:StartInstances",
                "ec2:StopInstances"
            ],
            "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
        }
    ]
}

Example IAM Policy to allow encrypted EBS volumes

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKeyWithoutPlaintext",
        "kms:Encrypt",
        "kms:DescribeKey",
        "kms:CreateGrant",
        "ec2:DetachVolume",
        "ec2:AttachVolume",
        "ec2:DeleteSnapshot",
        "ec2:DeleteTags",
        "ec2:CreateTags",
        "ec2:CreateVolume",
        "ec2:DeleteVolume",
        "ec2:CreateSnapshot"
      ],
      "Resource": [
        "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
        "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
        "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*",
        "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeTags",
        "ec2:DescribeVolumes",
        "ec2:DescribeSnapshots"
      ],
      "Resource": "*"
    }
  ]
}