Help improve this page
Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.
Deploy a sample application
In this topic, you deploy a sample application to your cluster.
Prerequisites
-
An existing Kubernetes cluster with at least one node. If you don't have an existing Amazon EKS cluster, you can deploy one using one of the Get started with Amazon EKS guides. If you're deploying a Windows application, then you must have Windows support enabled for your cluster and at least one Amazon EC2 Windows node.
-
Kubectl
installed on your computer. For more information, see Set up kubectl and eksctl. -
Kubectl
configured to communicate with your cluster. For more information, see Connect kubectl to an EKS cluster by creating a kubeconfig file. -
If you plan to deploy your sample workload to Fargate, then you must have an existing Fargate profile that includes the same namespace created in this tutorial, which is
eks-sample-app
, unless you change the name. If you used one of the getting started guides to create your cluster, then you'll have to create a new profile, or add the namespace to your existing profile, because the profile created in the getting started guides doesn't specify the namespace used in this tutorial. Your VPC must also have at least one private subnet.
To deploy a sample application
Though many variables are changeable in the following steps, we recommend only changing variable values where specified. Once you have a better understanding of Kubernetes Pods, deployments, and services, you can experiment with changing other values.
-
Create a namespace. A namespace allows you to group resources in Kubernetes. For more information, see Namespaces
in the Kubernetes documentation. If you plan to deploy your sample application to Simplify compute management with AWS Fargate, make sure that the value for namespace
in your Define which Pods use AWS Fargate when launched iseks-sample-app
.kubectl create namespace eks-sample-app
-
Create a Kubernetes deployment. This sample deployment pulls a container image from a public repository and deploys three replicas (individual Pods) of it to your cluster. To learn more, see Deployments
in the Kubernetes documentation. You can deploy the application to Linux or Windows nodes. If you're deploying to Fargate, then you can only deploy a Linux application. -
Save the following contents to a file named
eks-sample-deployment.yaml
. The containers in the sample application don't use network storage, but you might have applications that need to. For more information, see Store application data for your cluster. -
Apply the deployment manifest to your cluster.
kubectl apply -f eks-sample-deployment.yaml
-
-
Create a service. A service allows you to access all replicas through a single IP address or name. For more information, see Service
in the Kubernetes documentation. Though not implemented in the sample application, if you have applications that need to interact with other AWS services, we recommend that you create Kubernetes service accounts for your Pods, and associate them to AWS IAM accounts. By specifying service accounts, your Pods have only the minimum permissions that you specify for them to interact with other services. For more information, see IAM roles for service accounts. -
Save the following contents to a file named
eks-sample-service.yaml
. Kubernetes assigns the service its own IP address that is accessible only from within the cluster. To access the service from outside of your cluster, deploy the AWS Load Balancer Controller to load balance application or network traffic to the service. -
Apply the service manifest to your cluster.
kubectl apply -f eks-sample-service.yaml
-
-
View all resources that exist in the
eks-sample-app
namespace.kubectl get all -n eks-sample-app
An example output is as follows.
If you deployed Windows resources, then all instances of
in the following output arelinux
windows
. The otherexample values
may be different from your output.NAME READY STATUS RESTARTS AGE pod/eks-sample-
linux
-deployment-65b7669776-m6qxz
1/1 Running 0 27m pod/eks-sample-linux
-deployment-65b7669776-mmxvd
1/1 Running 0 27m pod/eks-sample-linux
-deployment-65b7669776-qzn22
1/1 Running 0 27m NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/eks-sample-linux
-service ClusterIP10.100.74.8
<none> 80/TCP 32m NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/eks-sample-linux
-deployment 3/3 3 3 27m NAME DESIRED CURRENT READY AGE replicaset.apps/eks-sample-linux
-deployment-776d8f8fd8
3 3 3 27mIn the output, you see the service and deployment that were specified in the sample manifests deployed in previous steps. You also see three Pods. This is because
3
replicas
were specified in the sample manifest. For more information about Pods, see Podsin the Kubernetes documentation. Kubernetes automatically creates the replicaset
resource, even though it isn't specified in the sample manifests. For more information aboutReplicaSets
, see ReplicaSetin the Kubernetes documentation. Note
Kubernetes maintains the number of replicas that are specified in the manifest. If this were a production deployment and you wanted Kubernetes to horizontally scale the number of replicas or vertically scale the compute resources for the Pods, use the Scale pod deployments with Horizontal Pod Autoscaler and the Adjust pod resources with Vertical Pod Autoscaler to do so.
-
View the details of the deployed service. If you deployed a Windows service, replace
withlinux
windows
.kubectl -n eks-sample-app describe service eks-sample-
linux
-serviceAn example output is as follows.
If you deployed Windows resources, then all instances of
in the following output arelinux
windows
. The otherexample values
may be different from your output.Name: eks-sample-
linux
-service Namespace: eks-sample-app Labels: app=eks-sample-linux
-app Annotations: <none> Selector: app=eks-sample-linux
-app Type: ClusterIP IP Families: <none> IP:10.100.74.8
IPs:10.100.74.8
Port: <unset> 80/TCP TargetPort: 80/TCP Endpoints:192.168.24.212
:80,192.168.50.185
:80,192.168.63.93
:80 Session Affinity: None Events: <none>In the previous output, the value for
IP:
is a unique IP address that can be reached from any node or Pod within the cluster, but it can't be reached from outside of the cluster. The values forEndpoints
are IP addresses assigned from within your VPC to the Pods that are part of the service. -
View the details of one of the Pods listed in the output when you viewed the namespace in a previous step. If you deployed a Windows app, replace
withlinux
windows
and replace
with the value returned for one of your Pods.776d8f8fd8-78w66
kubectl -n eks-sample-app describe pod eks-sample-
linux
-deployment-65b7669776-m6qxz
Abbreviated output
If you deployed Windows resources, then all instances of
in the following output arelinux
windows
. The other
may be different from your output.example values
Name: eks-sample-
linux
-deployment-65b7669776-m6qxz
Namespace: eks-sample-app Priority: 0 Node: ip-192-168-45-132
.us-west-2
.compute.internal/192.168.45.132
[...] IP:192.168.63.93
IPs: IP:192.168.63.93
Controlled By: ReplicaSet/eks-sample-linux
-deployment-65b7669776
[...] Conditions: Type Status Initialized True Ready True ContainersReady True PodScheduled True [...] Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 3m20s default-scheduler Successfully assigned eks-sample-app/eks-sample-linux
-deployment-65b7669776-m6qxz
to ip-192-168-45-132
.us-west-2
.compute.internal [...]In the previous output, the value for
IP:
is a unique IP that's assigned to the Pod from the CIDR block assigned to the subnet that the node is in. If you prefer to assign Pods IP addresses from different CIDR blocks, you can change the default behavior. For more information, see Deploy pods in alternate subnets with custom networking. You can also see that the Kubernetes scheduler scheduled the Pod on theNode
with the IP address
.192.168.45.132
Tip
Rather than using the command line, you can view many details about Pods, services, deployments, and other Kubernetes resources in the AWS Management Console. For more information, see View Kubernetes resources in the AWS Management Console.
-
Run a shell on the Pod that you described in the previous step, replacing
with the ID of one of your Pods.65b7669776-m6qxz
-
From the Pod shell, view the output from the web server that was installed with your deployment in a previous step. You only need to specify the service name. It is resolved to the service's IP address by CoreDNS, which is deployed with an Amazon EKS cluster, by default.
-
From the Pod shell, view the DNS server for the Pod.
-
Disconnect from the Pod by typing
exit
. -
Once you're finished with the sample application, you can remove the sample namespace, service, and deployment with the following command.
kubectl delete namespace eks-sample-app
Next Steps
After you deploy the sample application, you might want to try some of the following exercises: