Overview

Web service is a running container with a public endpoint. Main features of web service are:

• scalability - automatically add/remove containers based on CPU or memory usage (within your specified thresholds),
• zero downtime deployments (including various Blue/Green strategies),
• multiple options to provide container image, including zero-config packaging of code for Typescript/Javascript, Python, Java and Go,
• easy domain management with SSL/TLS certificates,
• ability to offload containers by putting CDN(cache) in-front of your endpoint,
• no hassle with managing and patching servers or VMs,
• seamless connectivity with other resources.

Get started

Start with web service by trying one of our starter projects or checkout example web service

Starter projects

• (Typescript) ExpressJS with Postgres
• (Typescript) NestJS with Postgres
• (Typescript) NextJS SSR website
• (Typescript) NuxtJS SSR website
• (Python) Django API with Postgres
• (Python) Flask API with Postgres
• (Go) Gin API with Postgres
• (PHP) Laravel SSR website
• (Java) Spring Boot API with Postgres
• (Ruby) Ruby on Rails with Postgres

Example web service

Copy
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  res.send({ message: 'Hello' });
});

// for your use port number stored in PORT environment variable for your application
// this environment variable is automatically injected by Stacktape
app.listen(process.env.PORT, () => {
  console.info(`Server running on port ${process.env.PORT}`);
});

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048

Under the hood

Under the hood Stacktape uses AWS ECS(Elastic Container Service) to orchestrate your containers. Containers can be ran using Fargate or EC2 instances:

• Fargate - technology which allows you to run containers without having to manage servers or clusters. This means you don't have to worry about administration tasks such as scaling, VM security, OS security & much more.
• EC2 instances - VMs running on AWS

ECS Services are self healing - if your container instance dies for any reason, it is automatically replaced with a healthy instance. They auto-scale from the box(within configured boundaries) leveraging the AWS Application Auto Scaling service.

Depending on the chosen load balancing type, traffic to the web-service containers is delivered and distributed either using HTTP API gateway(default) or Application load balancer. Stacktape automatically creates these gateway/load balancer as a part of creation of web service.

When to use

If you are unsure which resource type is best suitable for your app, following table provides short comparison of all container-based resource types offered by Stacktape.

Advantages

• Control over underlying environment - Web service can run any Docker image or image built using your own Dockerfile.
• Price for compute resources with predictable load - Compared to functions, web services are cheaper if your compute resource has a predictable load.
• Load-balanced and auto-scalable - Web services can automatically horizontally scale based on the CPU and Memory utilization.
• High availability - Web services run in multiple Availability Zones.
• Secure by default - Underlying environment is securely managed by AWS.

Disadvantages

• Scaling speed - Unlike lambda functions that scale almost instantly, web service requires more time - from several seconds to few minutes to add another container.

• Not fully serverless - While web services can automatically scale up and down, they can't scale to 0. This means, if your compute resource is unused, you are still paying for at least one instance (minimum ~$8/month)

Image

• Web Service is a running instance of a Docker image.
• The image of the container can be supplied in 4 different ways:
  • images built using stacktape-image-buildpack
  • images built using external-buildpack
  • images built from the custom-dockerfile
  • prebuilt-images

Environment variables

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      environment:
        - name: STATIC_ENV_VAR
          value: my-env-var
        - name: DYNAMICALLY_SET_ENV_VAR
          value: $MyCustomDirective('input-for-my-directive')
        - name: DB_HOST
          value: $ResourceParam('myDatabase', 'host')
        - name: DB_PASSWORD
          value: $Secret('dbSecret.password')
      resources:
        cpu: 2
        memory: 2048

Healthcheck

The purpose of the container health check is to monitor the health of the container from the inside.

Once an essential container of an instance is determined UNHEALTHY, the instance is automatically replaced with a new one.

• Example: A shell command sends a curl request every 20 seconds to determine if the service is available. If the request fails (or doesn't return in 5 seconds), the command returns with non-zero exit code, and the healthcheck is considered failed.

Copy
resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      internalHealthCheck:
        healthCheckCommand: ['CMD-SHELL', 'curl -f http://localhost/ || exit 1']
        intervalSeconds: 20
        timeoutSeconds: 5
        startPeriodSeconds: 150
        retries: 2
      resources:
        cpu: 2
        memory: 2048

Shutdown

• When a running web service instance is deregistered (removed), all running containers receive a SIGTERM signal.
• By default, you then have 2 seconds to clean up. After 2 seconds, your process receives a SIGKILL signal.
• You can set the timeout by using stopTimeout property (must be between 2 - 120 seconds).
• Setting stop timeout can help you give container the time to "finish the job" or to "cleanup" when deploying new version of container or when deleting the service.

Copy
process.on('SIGTERM', () => {
  console.info('Received SIGTERM signal. Cleaning up and exiting process...');

  // Finish any outstanding requests, or close a database connection...

  process.exit(0);
});

Logging

• Every time your code outputs (prints) something to the stdout or stderr, your log will be captured and stored in a AWS CloudWatch log group.
• You can browse your logs in 2 ways:
  • Browse logs in the AWS CloudWatch console. To get direct link to your logs you have 2 options:
    1. Go to stacktape console. Link is among information about your stack and resource.
    2. You can use stacktape stack-info command.
  • Browse logs using stacktape logs command that will print logs to the console.
• Please note that storing log data can become costly over time. To avoid excessive charges, you can configure retentionDays.

Forwarding logs

It is possible to forward logs to the third party services/databases. See page Forwarding logs for more information and examples.

Resources

In resources section, you specify amounts of cpu/memory and EC2 instance types available to your service.

There are two ways to run your containers:

1. using Fargate

   • Fargate is a serverless, pay-as-you-go compute engine for running containers without having to manage underlying instances (servers).
   • With Fargate you only need to specify cpu and memory required for your service.
   • While slightly more expensive, using Fargate is often preferred in strictly regulated industries since running containers on Fargate meets the standards for PCI DSS Level 1, ISO 9001, ISO 27001, ISO 27017, ISO 27018, SOC 1, SOC 2, SOC 3 out of the box.

2. using EC2 instances

   • EC2 instances are virtual machines (VMs) ran on AWS cloud.
   • Containers are placed on the EC2 instances which are added and removed depending on service needs.
   • You can choose instance type that suit your resource requirements the best.

Following applies when configuring resources section of your service:

Using Fargate

If you do not specify instanceTypes property in resources section, Fargate is used to run your containers.

Copy
resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        cpu: 0.25
        memory: 512

Using EC2 instances

If you specify instanceTypes property in resources section, EC2 instances are used to run your containers.

Copy
resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        instanceTypes:
          - c5.large

Placing containers on EC2

Stacktape aims to achieve 100% utilization of your EC2 instances. However this is not always possible and following behavior can be expected:

• If you only specify one type in instanceTypes and you do NOT set memory and cpu then Stacktape sets memory and cpu to fit the EC2 instance type precisely(see also Default cpu and memory section).

  This means that if your service scales(new instance of service is added), new EC2 instance is added as well.

• If you specify cpu and memory properties alongside instanceTypes, they will be respected. If the EC2 instance is larger (has more resources) than specified cpu and memory, AWS places instances of your service on available EC2 instances using binpack strategy. This strategy aims to put as many instances of your service on the available EC2 instances as possible(to maximize utilization).

Scaling

In scaling section, you can configure scaling behavior of your service. You can configure:

• Minimum and maximum amount of concurrently running instances of your service.
• Conditions which trigger the scaling (up or down) using a scaling policy.

Scaling policy

• A scaling policy specifies CPU and memory metric thresholds which trigger the scaling process.

• Depending on the thresholds, the compute resource can either scale out (add instances) or scale in (remove instances).

• If both keepAvgCpuUtilizationUnder and keepAvgMemoryUtilizationUnder are used, the compute resource will scale-out if one of the metrics is above the target value. However, to scale in, both of these metrics need to be below their respective target values.

• Scaling policy is more aggressive in adding capacity then removing capacity. For example, if the policy's specified metric reaches its target value, the policy assumes that your application is already heavily loaded. So it responds by adding capacity proportional to the metric value as fast as it can. The higher the metric, the more capacity is added.

• When the metric falls below the target value, the policy expects that utilization will eventually increase again. Therefore it slows down the scale-in process by removing capacity only when utilization passes a threshold that is far enough below the target value (usually 20% lower).

Copy
resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      resources:
        cpu: 0.5
        memory: 1024
      scaling:
        minInstances: 1
        maxInstances: 5
        scalingPolicy:
          keepAvgMemoryUtilizationUnder: 80
          keepAvgCpuUtilizationUnder: 80

Storage

• Each web service instance has access to its own ephemeral storage. It's removed after the web service instances is removed.
• It has a fixed size of 20GB.
• If you have 2 concurrently running web service instances, they do not share this storage.
• To store data persistently, consider using Buckets.

Accessing other resources

• For most of the AWS resources, resource-to-resource communication is not allowed by default. This helps to enforce security and resource isolation. Access must be explicitly granted using IAM (Identity and Access Management) permissions.

• Access control of Relational Databases is not managed by IAM. These resources are not "cloud-native" by design and have their own access control mechanism (connection string with username and password). They are accessible by default, and you don't need to grant any extra IAM permissions. You can further restrict the access to your relational databases by configuring their access control mode.

• Stacktape automatically handles IAM permissions for the underlying AWS services that it creates (i.e. granting web services permission to write logs to Cloudwatch, allowing web services to communicate with their event source and many others).

If your compute resource needs to communicate with other infrastructure components, you need to add permissions manually. You can do this in 2 ways:

Using connectTo

• List of resource names or AWS services that this service will be able to access (basic IAM permissions will be granted automatically). Granted permissions differ based on the resource.
• Works only for resources managed by Stacktape in resources section (not arbitrary Cloudformation resources)
• This is useful if you don't want to deal with IAM permissions yourself. Handling permissions using raw IAM role statements can be cumbersome, time-consuming and error-prone. Moreover, when using connectTo property, Stacktape automatically injects information about resource you are connecting to as environment variables into your workload.

Copy
resources:
  photosBucket:
    type: bucket

  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/index.ts
      connectTo:
        # access to the bucket
        - photosBucket
        # access to AWS SES
        - aws:ses
      resources:
        cpu: 0.25
        memory: 512

Using iamRoleStatements

• List of raw IAM role statement objects. These will be appended to the web service's role.
• Allows you to set granular control over your web service's permissions.
• Can be used to give access to any Cloudformation resource

Copy
resources:
  myWebService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: server/index.ts
      iamRoleStatements:
        - Resource:
            - $CfResourceParam('NotificationTopic', 'Arn')
          Effect: 'Allow'
          Action:
            - 'sns:Publish'
      resources:
        cpu: 2
        memory: 2048

cloudformationResources:
  NotificationTopic:
    Type: 'AWS::SNS::Topic'

Load balancing

LoadBalancing property is used to configure what type of entry point is used for distributing traffic to containers:

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      loadBalancing:
        type: application-load-balancer # default is http-api-gateway

Deployment strategies

Using deployment strategies you configure the way your web-service is updated when deploying new version. By default, rolling update is used. However you can use deployment property to choose different strategy.

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      loadBalancing:
        type: application-load-balancer
      deployment:
        strategy: Canary10Percent5Minutes

Hook functions

You can use hooks to perform checks using lambda-functions.

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      loadBalancing:
        type: application-load-balancer
      deployment:
        strategy: Canary10Percent5Minutes
        afterTrafficShiftFunction: validateDeployment

  validateDeployment:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: src/validate-deployment.ts

Copy
import { CodeDeployClient, PutLifecycleEventHookExecutionStatusCommand } from '@aws-sdk/client-codedeploy';

const client = new CodeDeployClient({});

export default async (event) => {
  // read DeploymentId and LifecycleEventHookExecutionId from payload
  const { DeploymentId, LifecycleEventHookExecutionId } = event;

  // performing validations here

  await client.send(
    new PutLifecycleEventHookExecutionStatusCommand({
      deploymentId: DeploymentId,
      lifecycleEventHookExecutionId: LifecycleEventHookExecutionId,
      status: 'Succeeded' // status can be 'Succeeded' or 'Failed'
    })
  );
};

Test traffic listener

When using beforeAllowTraffic hook you can use test listener(test port) to send test traffic to the new version of workload before allowing any production traffic.

By default the test listener is automatically created on port 8080.

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      loadBalancing:
        type: application-load-balancer
      deployment:
        strategy: Canary10Percent5Minutes
        beforeAllowTrafficFunction: testDeployment

  testDeployment:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: src/test-deployment.ts
      environment:
        - name: WEB_SERVICE_URL
          value: $ResourceParam('webService', 'url')
        - name: TEST_LISTENER_PORT
          value: 8080

Copy
import { CodeDeployClient, PutLifecycleEventHookExecutionStatusCommand } from '@aws-sdk/client-codedeploy';
import fetch from 'node-fetch';

const client = new CodeDeployClient({});

export default async (event: { DeploymentId: string; LifecycleEventHookExecutionId: string }) => {
  const { DeploymentId: deploymentId, LifecycleEventHookExecutionId: lifecycleEventHookExecutionId } = event;
  try {
    // test new version by using test listener port
    await fetch(`${process.env.WEB_SERVICE_URL}:${process.env.TEST_LISTENER_PORT}`);
    // validate result
    // do some other tests ...
  } catch (err) {
    // send FAILED status if error occurred
    await client.send(
      new PutLifecycleEventHookExecutionStatusCommand({
        deploymentId,
        lifecycleEventHookExecutionId,
        status: 'Failed'
      })
    );
    throw err;
  }
  // send SUCCEEDED status after successful testing
  await client.send(
    new PutLifecycleEventHookExecutionStatusCommand({
      deploymentId,
      lifecycleEventHookExecutionId,
      status: 'Succeeded'
    })
  );
};

Default VPC connection

• Certain AWS services (such as Relational Databases) must be connected to a VPC (Virtual private cloud) to be able to run. For stacks that include these resources, Stacktape does 2 things:
  • creates a default VPC
  • connects the VPC-requiring resources to the default VPC.
• web services are connected to the default VPC of your stack by default. This means that web services can communicate with resources that have their accessibility mode set to vpc without any extra configuration.
• To learn more about VPCs and accessibility modes, refer to VPC docs, accessing relational databases, accessing redis clusters and accessing MongoDb Atlas clusters.

CORS

Cross-origin resource sharing (CORS) is a browser security feature that restricts cross-origin HTTP requests that are initiated from scripts running in the browser.

A cross-origin HTTP request is a request that is made to a different domain or a different subdomain than the one browser is currently on.

Example: If your website has domain mydomain.com and it communicates with your web-service which has domain api.mydomain.com then the browser must perform cross origin request when communicating with this web-service.

There are two types of cross-origin requests:

1. Simple requests

   • requests that do not require CORS preflight.
   • To understand what is considered a simple request refer to Mozilla docs.
   • You do not need to configure CORS on your gateway for these types of requests. However, responses from your application should still include Access-Control-Allow-Origin header where the value of the header key is set to *(any origin) or is set to the origins allowed to access that resource. Refer to Mozilla docs for more information.

2. NON-simple (preflighted) requests

   • all cross origin requests that are not considered simple are NON-simple and require preflight requests.
   • If you send NON-simple CORS requests from browser to your API, you can enable CORS which takes care of preflight requests, and sets the necessary response headers.

If you need to use NON-simple cross origin requests you can enable CORS. CORS can be enabled with a single line.

Copy
resources:
  myWebService:
    type: 'web-service'
    properties:
      resources:
        cpu: 2
        memory: 2048
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      cors:
        enabled: true

You can additionally configure CORS headers by setting properties in cors configuration.

Custom domain names

If you do not have a custom domain and want one, read the section Registering domain on the Domains and TLS certificates page.

If you already have an existing domain and you wish to use it with your app, there are two approaches:

1. Using Stacktape to manage domains and certs - you must use Route53 in your AWS account as your DNS.
2. Using 3rd party DNS provider - such as GoDaddy, Cloudflare etc. You must handle domains and generate certificates yourself.

For more information about domain management options, refer to Domains and TLS certificates page.

Using Stacktape to manage domains and certs

Copy
resources:
  myWebService:
    type: web-service
    properties:
      resources:
        cpu: 2
        memory: 2048
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      customDomains:
        - domainName: whatever.mydomain.com

Using 3rd party DNS

To use 3rd party provider follow these steps:

1. Create/import a custom TLS certificate for your domain in AWS console. Copy certificate ARN; you will need it in the next step.
2. After the certificate is validated (Issued), assign your domain to your resource:
   • use the ARN of your certificate as customCertificateArn
   • disable DNS record creation (because you are using third party DNS)

Copy
resources:
  apiService:
    type: web-service
    properties:
      resources:
        cpu: 2
        memory: 2048
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>

3. After you deploy your web service, you can find the domain name in Stacktape console in:

   Your project and stage > Click on your Web service resource to see its domain

   Once you have the domain name, you can point DNS record to this domain using your DNS provider:

   • Use ALIAS record type for root domains (i.e mydomain.com)
   • Use CNAME record type for subdomains (i.e www.mydomain.com or staging.mydomain.com

CDN

You can configure AWS Cloudfront CDN (Content Delivery Network) to be in front of your web-service.

For information about using CDN refer to our CDN docs.

Copy
resources:
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      cdn:
        enabled: true

Using firewall

To lean more, check web-app-firewall documentation.

Copy
resources:
  myFirewall:
    type: web-app-firewall
    properties:
      scope: regional
  webService:
    type: web-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: src/main.ts
      resources:
        cpu: 2
        memory: 2048
      useFirewall: myFirewall

Referenceable parameters

Pricing

You are charged for:

• Virtual CPU / hour:

  • depending on the region $0.04048 - $0.0696

• Memory GB / hour:

  • depending on the region $0.004445 - $0.0076

The duration is rounded to 1 second with a 1 minute minimum. To learn more, refer to AWS Fargate pricing.

API reference