diff --git a/README.md b/README.md index 6beb5cbea..4c35c5126 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,16 @@ The config file is in TOML format, and an example lives in `providers/azure/exam See the [ACI Readme](providers/azure/README.md) +### AWS Fargate Provider + +The AWS Fargate provider allows you to deploy pods to [AWS Fargate](https://aws.amazon.com/fargate/). +Your pods on AWS Fargate have access to VPC networking with dedicated ENIs in your subnets, public +IP addresses to connect to the internet, private IP addresses to connect to your Kubernetes cluster, +security groups, IAM roles, CloudWatch Logs and many other AWS services. Pods on Fargate can +co-exist with pods on regular worker nodes in the same Kubernetes cluster. + +Easy instructions and a sample configuration file is available in the [AWS Fargate provider documentation](providers/aws/README.md). + ### Hyper.sh Provider The Hyper.sh Provider allows Kubernetes clusters to deploy Hyper.sh containers diff --git a/providers/aws/README.md b/providers/aws/README.md index 59b5c2cbe..4eb146bcd 100644 --- a/providers/aws/README.md +++ b/providers/aws/README.md @@ -1,32 +1,85 @@ # AWS Fargate -[AWS Fargate](https://aws.amazon.com/fargate/) is a technology for deploying and managing containers -without having to manage any of the underlying infrastructure. With AWS Fargate, you no longer have -to provision, configure, and scale clusters of virtual machines to run containers. This removes the -need to choose server types, decide when to scale your clusters, or optimize cluster packing. +[AWS Fargate](https://aws.amazon.com/fargate/) is a technology that allows you to run containers +without having to manage servers or clusters. With AWS Fargate, you no longer have to provision, +configure and scale clusters of virtual machines to run containers. This removes the need to choose +server types, decide when to scale your clusters, or optimize cluster packing. Fargate lets you +focus on designing and building your applications instead of managing the infrastructure that runs +them. Fargate makes it easy to scale your applications. You no longer have to worry about provisioning -enough compute resources. You can launch tens or tens of thousands of containers in seconds. Fargate -lets you focus on designing and building your applications instead of managing the infrastructure -that runs them. +enough compute resources. You can launch tens or tens of thousands of containers in seconds. With Fargate, billing is at a per second granularity and you only pay for what you use. You pay for the amount of vCPU and memory resources your containerized application requests. vCPU and memory resources are calculated from the time your container images are pulled until they terminate, rounded up to the nearest second. -## Fargate virtual-kubelet provider +## AWS Fargate virtual-kubelet provider -Fargate virtual-kubelet provider configures a Fargate cluster in AWS. Fargate resources show as a -node in your Kubernetes cluster. Pods scheduled on the Fargate node are deployed as Fargate -instances as if Fargate is a standard Kubernetes node. +> Virtual-kubelet and the AWS Fargate virtual-kubelet provider are in very early stages of development.
+> DO NOT run them in any Kubernetes production environment or connect to any Fargate production cluster. + +AWS Fargate virtual-kubelet provider connects your Kubernetes cluster to a Fargate cluster in AWS. +The Fargate cluster is exposed as a virtual node with the CPU and memory capacity that you choose. +Pods scheduled on the virtual node run on Fargate like they would run on a standard Kubernetes node. + +## Prerequisites + +If you have never used Fargate before, the easiest way to get started is to run Fargate's +[First run experience](https://console.aws.amazon.com/ecs/home?region=us-east-1#/firstRun). This +will setup Fargate in your AWS account with the default settings. It will create a default Fargate +cluster, IAM roles, a default VPC with an internet gateway and a default security group. You can +always fine-tune individual settings later. + +Once you have your first application on Fargate running, move on to the next section below. + +You may also want to install the +[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) +and visit the [AWS ECS console](https://console.aws.amazon.com/ecs) to take a closer look at your +Fargate resources. ## Configuration -A [sample configuration file](fargate.toml) is available. +In order to run virtual-kubelet for AWS Fargate, you need a simple configuration file. We have +provided a [sample configuration file](fargate.toml) for you that contains reasonable defaults and +brief descriptions for each field. -## Usage +Create a copy of the sample configuration file and customize it. -`` +If you ran the first-run experience, you only need to provide a subnet and set +AssignPublicIPv4Address to true. You can leave the security groups list blank to use the default +security group. You can learn your subnet ID in +[AWS console VPC subnets page](https://console.aws.amazon.com/vpc/home?#subnets). You +also need to update your [security group](https://console.aws.amazon.com/vpc/home?#securityGroups) +to allow traffic to your pods. + +## Authentication via IAM + +Virtual-kubelet needs permission to schedule pods on Fargate on your behalf. The easiest way to do +so is to run virtual-kubelet on a worker node in your Kubernetes cluster in EC2. Attach an IAM role +to the worker node EC2 instance and give it permission to your Fargate cluster. + +## Connecting virtual-kubelet to your Kubernetes cluster + +Copy the virtual-kubelet binary and your configuration file to your Kubernetes worker node in EC2. + +```console virtual-kubelet --provider aws --provider-config fargate.toml -`` +``` + +In your Kubernetes cluster, confirm that the virtual-kubelet shows up as a node. +```console +kubectl get nodes + +NAME STATUS ROLES AGE VERSION +virtual-kubelet Ready agent 5s v1.8.3 +``` + +To disconnect, stop the virtual-kubelet process. + +## Deploying Kubernetes pods in AWS Fargate + +Virtual-kubelet currently supports only a subset of regular kubelet functionality. In order to not +break existing pod deployments, pods that are to be deployed on Fargate require an explicit node +selector that points to the virtual node. diff --git a/providers/aws/fargate.toml b/providers/aws/fargate.toml index db302b5fb..45ecf878a 100644 --- a/providers/aws/fargate.toml +++ b/providers/aws/fargate.toml @@ -1,5 +1,5 @@ # -# Example configuration file for virtual-kubelet AWS Fargate provider. +# Example configuration file for AWS Fargate virtual-kubelet provider. # # Usage: # virtual-kubelet --provider aws --provider-config fargate.toml @@ -8,38 +8,40 @@ # AWS region where Fargate resources are provisioned. Mandatory. Region = "us-east-1" -# Fargate cluster name. Optional. Defaults to "default". +# AWS Fargate cluster name. Optional. Defaults to "default". # If a cluster with this name does not exist in the region, virtual-kubelet will create it. -# Although the same Fargate cluster can be shared by multiple virtual-kubelets, -# we recommend to create a dedicated Fargate cluster for each virtual-kubelet. -ClusterName = "fargate1" +# Creating a dedicated Fargate cluster for each virtual-kubelet is recommended. +ClusterName = "default" -# List of subnets that pods are connected to. Mandatory. +# List of subnets that pod ENIs are connected to. Mandatory. Subnets = ["subnet-12345678"] -# List of security groups for pods. Optional. -# If omitted, pods inherit their VPC's default security group. -SecurityGroups = ["sg-12345678", "sg-87654321"] +# List of security groups associated with pod ENIs. Optional. +# If omitted, pod ENIs inherit their VPC's default security group. +SecurityGroups = ["sg-12345678"] # Whether pod ENIs are assigned a public IPv4 address. Optional. Defaults to false. +# If your pod requires internet access (e.g. to download container images from ECR or Docker Hub), +# this should be set to "true" for pods on public subnets with internet gateways, +# and to "false" for pods on private subnets with NAT gateways. AssignPublicIPv4Address = false -# Role assumed by AWS Fargate to execute your task. Optional. +# Role assumed by AWS Fargate to execute your pod. Optional. # https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html ExecutionRoleArn = "" -# AWS CloudWatch Log Group Name used to store container logs. Optional. -# If omitted, no container logs will be stored and retrievable. -CloudWatchLogGroupName = "/ecs/virtual-kubelet-logs" +# Amazon CloudWatch log group name used to store container logs. Optional. +# If omitted, container logs will not be available. +CloudWatchLogGroupName = "" -# Fargate platform version. Optional. Defaults to "LATEST". +# AWS Fargate platform version. Optional. Defaults to "LATEST". # https://docs.aws.amazon.com/AmazonECS/latest/developerguide/platform_versions.html PlatformVersion = "LATEST" # Operating system for pods. Optional. Defaults to "Linux". OperatingSystem = "Linux" -# Fargate capacity advertised by virtual-kubelet. Optional. Defaults to the values below. +# AWS Fargate capacity advertised by virtual-kubelet. Optional. Defaults to the values below. # Capacity is specified using Kubernetes resource format. # https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ CPU = "20"