Deploy to a new Kubernetes cluster

The Encore platform gives you flexibility in where you run your applications. You have two options for Kubernetes deployments:

1. Deploy to a new cluster: the Encore platform can automatically provision and manage a new Kubernetes cluster in your cloud account on AWS or GCP.
2. Use an existing cluster: Deploy to your pre-existing GKE or EKS cluster (see instructions here)

All infrastructure provisioning is automated, and configuration is managed through the Encore platform Dashboard, keeping your application code clean and infrastructure-agnostic.

Deploying to a new Kubernetes cluster

1. Connect your cloud account: Ensure your cloud account (Google Cloud Platform or AWS) is connected to the Encore platform. (See docs)

2. Create environment: Open your app in the Encore platform dashboard and go to Environments, then click on Create Environment.

Next, select your cloud (AWS or GCP) and then specify Kubernetes as the compute platform. On GCP, the Encore platform deploys to GKE. On AWS, it deploys to EKS, and you choose what your services run on (see EKS compute below).

You can also configure if you want to allocate all services in one process or run one process per service.

3. Push your code: To deploy, commit and push your code to the branch you configured as the deployment trigger. You can also trigger a manual deploy from the Cloud Dashboard by going to the Environment Overview page and clicking on Deploy.

4. Automatic deployment by the Encore platform: Once you've triggered the deploy, the Encore platform will automatically provision and deploy the necessary infrastructure on Kubernetes, per your environment configuration in the Cloud Dashboard. You can monitor the status of your deploy and view your environment's details through the Encore platform Dashboard.

5. Accessing your cluster with kubectl: You can access your cluster using the kubectl CLI tool. See the docs for how to do this.

EKS compute

On AWS, you choose what your services' pods run on when you create the environment:

The cluster's system components (CoreDNS, and on Fargate and node groups the AWS Load Balancer Controller) run on the same compute as your services.

Auto Mode is part of how the cluster is created, so it can't be turned on or off for an existing environment.

Fargate

Fargate sizes and bills each pod by its resource requests, rounded up to the nearest Fargate configuration. Encore gives each service container a request of 1 vCPU and 2 GiB of memory, unless you configure other requests.

Node groups

Encore creates one managed node group of m7i.xlarge instances (on-demand, x86). The Cluster Autoscaler adds and removes nodes between the group's minimum and maximum size as your pods need them. Encore keeps the node group's Kubernetes version in step with the cluster's.

Each service still gets its own security group, using security groups for pods, so network access to your databases and caches stays scoped per service. This limits how many pods fit on a node: an m7i.xlarge holds up to 18 pods with a security group.

Auto Mode

Encore creates a node pool and node class of its own for your services, running on-demand x86 instances from the general purpose, compute optimized and memory optimized families. EKS chooses the instance types, scales the nodes and replaces them as needed. EKS Auto Mode also provides the load balancing and DNS, so Encore doesn't install the AWS Load Balancer Controller.

EKS Auto Mode doesn't support security groups for pods. Instead, all of the environment's nodes share one security group, and access to your databases and caches is granted to that group. Network access is therefore scoped to the environment rather than to each service. Database credentials are per container, as on every Encore deployment: services that run in the same container share them (see Database roles).

Infrastructure Overview

The Encore platform simplifies the process of deploying applications by automatically provisioning and managing the necessary Kubernetes components. Here's an overview of the components the Encore platform manages and how they work together to support your applications.

Namespace Management

The Encore platform creates a unique namespace for each environment deployed to your Kubernetes cluster, ensuring complete isolation between different environments of your application.

Secrets Management

The Encore platform provides comprehensive secrets management through deep integration with Kubernetes Secrets. Application secrets that you configure in the Encore platform are automatically stored as Kubernetes Secrets and made available to your services at runtime. This includes both application-specific secrets that you define, as well as infrastructure secrets like database credentials that the Encore platform manages automatically.

Service accounts are automatically bound to the appropriate secrets they need access to, ensuring each service can only access the secrets it requires. This follows the principle of least privilege and helps maintain a strong security posture.

Ingress Configuration

The Encore platform provisions and manages ingress for your applications through a cloud provider-specific ingress controller. The ingress controller is automatically configured to handle incoming traffic and route it securely to your application's Encore Gateway service. It manages TLS certificates automatically to ensure all traffic is encrypted, and provides fine-grained control over which services are accessible from the public internet. The controller configuration is optimized for your specific cloud provider to ensure the best possible performance and reliability.

Service Management

Deployments

The Encore platform manages the deployment configuration for each service in your application. Each service is deployed as a separate Kubernetes deployment, allowing for independent scaling and management. The deployment configurations are automatically generated and optimized based on your service's requirements.

For each service, the Encore platform configures the pod specifications with appropriate resource requests and limits, health checks, and container settings. Runtime configurations like environment variables and command arguments are automatically set based on your application's needs. The container orchestration is handled seamlessly, with the Encore platform managing pod scheduling, updates, and scaling to ensure your services run reliably and efficiently.

Network Configuration

The Encore platform provides a comprehensive networking setup through Kubernetes Service resources. Each service in your application gets assigned a unique cluster IP address, enabling reliable internal communication between services. This IP allocation works in conjunction with Kubernetes' built-in service discovery mechanism, allowing services to locate and communicate with each other using consistent internal DNS names. The internal service routing ensures that requests are efficiently distributed across all available pods for each service, providing automatic load balancing and failover capabilities.

Identity and Access

The Encore platform provides comprehensive service identity management through Kubernetes service accounts. Each pod is assigned its own dedicated service account, which handles authentication with the Kubernetes API and enables secure access to resources. These service accounts are automatically bound to the specific secrets and permissions required by each service.

For cloud provider integration, the Encore platform maps the service accounts to appropriate IAM roles, enabling secure access to cloud resources like databases and object storage. Following the principle of least privilege, the Encore platform configures the minimum required permissions for each service account, ensuring services can only access the resources they explicitly need.

All these configurations are automatically maintained and updated by the Encore platform as you develop your application, ensuring your infrastructure stays aligned with your application's needs.