Getting started with Serverless Containers

Written by

Updated at November 14, 2024

Prepare a Docker image for a container
- App and Dockerfile examples
Add the image to Serverless Containers
- Create a container
- Create a container revision
Invoke the container
What's next

In this tutorial, you will prepare a Docker image for a container in Yandex Container Registry and add it to Serverless Containers.

Prepare a Docker image for a container

A Docker image is an executable package that contains everything you need to run an application: code, runtime environment, libraries, environment variables, and configuration files.

The application must retrieve the number of the port for receiving requests, from the PORT environment variable. The variable value is set by the service automatically.

To prepare a container's Docker image:

Create a registry in Yandex Container Registry.
Create and build a Docker image based on Dockerfile.
Push the Docker image to the registry.

App and Dockerfile examples

Node.js

Python

index.js

const express = require('express');

const app = express();
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

app.get("/hello", (req, res) => {
    var ip = req.headers['x-forwarded-for']
    console.log(`Request from ${ip}`);
    return res.send("Hello!");
});

app.listen(process.env.PORT, () => {
    console.log(`App listening at port ${process.env.PORT}`);
});

Dockerfile

FROM node:16-slim

WORKDIR /app
RUN npm install express
COPY ./index.js .

CMD [ "node", "index.js" ]

index.py

import os
from sanic import Sanic
from sanic.response import text

app = Sanic(__name__)

@app.after_server_start
async def after_server_start(app, loop):
    print(f"App listening at port {os.environ['PORT']}")

@app.route("/hello")
async def hello(request):
    ip = request.headers["X-Forwarded-For"]
    print(f"Request from {ip}")
    return text("Hello!")

if __name__ == "__main__":
    app.run(host='0.0.0.0', port=int(os.environ['PORT']), motd=False, access_log=False)

Dockerfile

FROM python:3.10-slim

WORKDIR /app
RUN pip install --no-cache-dir --prefer-binary sanic
COPY ./index.py .

CMD [ "python", "index.py" ]

index.go

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    portStr := os.Getenv("PORT")
    fmt.Printf("App listening at port %s\n", portStr)
    http.Handle("/hello", hwHandler{})
    http.ListenAndServe(":"+portStr, nil)
}

type hwHandler struct{}

func (hwHandler) ServeHTTP(writer http.ResponseWriter, request *http.Request) {
    ip := request.Header.Get("X-Forwarded-For")
    fmt.Printf("Request from %s\n", ip)
    writer.WriteHeader(200)
    _, _ = writer.Write([]byte("Hello!"))
}

Dockerfile

FROM golang:latest AS build

WORKDIR /app
ADD index.go .
RUN GOARCH=amd64 go build -a -tags netgo -ldflags '-w -extldflags "-static"' -o server-app *.go

FROM scratch
COPY --from=build /app/server-app /server-app

ENTRYPOINT ["/server-app"]

Add the image to Serverless Containers

Create a container

Management console

CLI

Terraform

API

In the management console, go to the folder where you want to create a container.
Select Serverless Containers.
Click Create container.
Enter a name and a description for the container. The name format is as follows:
- The name must be from 3 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter and the last character cannot be a hyphen.
Click Create.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

To create a container, run this command:

yc serverless container create --name <container_name>

Result:

id: bba3fva6ka5g********
folder_id: b1gqvft7kjk3********
created_at: "2021-07-09T14:49:00.891Z"
name: my-beta-container
url: https://bba3fva6ka5g********.containers.yandexcloud.net/
status: ACTIVE

Terraform allows you to quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. Configuration files store the infrastructure description in the HashiCorp Configuration Language (HCL). Terraform and its providers are distributed under the Business Source License.

For more information about the provider resources, see the documentation on the Terraform website or the mirror.

If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

If you don't have Terraform, install it and configure the Yandex Cloud provider.

To create a container and its revision:

Note

If a registry or repository containing the Docker image is not public, you need to specify a service account with permission to download the Docker image in the revision settings. For example, the container-registry.images.puller role to the folder or registry containing the Docker image.

If a service account is specified in the revision settings, the user or the service account creating the revision must have the iam.serviceAccounts.user role. It confirms the right to use the service account.

In the configuration file, describe the parameters of the resources you want to create:
- name: Container name. This is a required parameter. The naming requirements are as follows:
  - The name must be from 3 to 63 characters long.
  - It may contain lowercase Latin letters, numbers, and hyphens.
  - The first character must be a letter and the last character cannot be a hyphen.
- memory: Amount of memory allocated to a container, MB. The default value is 128 MB.
- service_account_id: Service account ID.
- url: URL of the Docker image in Yandex Container Registry.
Here is an example of the configuration file structure:
```
provider "yandex" {
 token     = "<OAuth_token>"
 cloud_id  = "<cloud_ID>"
 folder_id = "<folder_ID>"
 zone      = "ru-central1-a"
}

resource "yandex_serverless_container" "test-container" {
  name               = "<container_name>"
  memory             = <memory_size>
  service_account_id = "<service_account_ID>"
  image {
      url = "<Docker_image_URL>"
  }
}
```
For more information about the yandex_serverless_container resource parameters in Terraform, see the relevant provider documentation.
Make sure the configuration files are correct.
1. In the command line, go to the folder where you created the configuration file.
2. Run a check using this command:
```
terraform plan
```
If the configuration is described correctly, the terminal will display a list of created resources and their parameters. If the configuration contains any errors, Terraform will point them out.
Deploy cloud resources.
1. If the configuration does not contain any errors, run this command:
```
terraform apply
```
2. Confirm creating the resources: type yes in the terminal and press Enter.
  
  All the resources you need will then be created in the specified folder. You can check the new resources and their settings using the management console or this CLI command:
```
yc serverless container list
```

To create a container, use the create REST API method for the Container resource or the ContainerService/Create gRPC API call.

Create a container revision

Management console

CLI

Terraform

API

In the management console, select the folder with your container.
Select Serverless Containers.
Select the container whose revision you want to create.
Go to the Editor tab.
Under Image settings, you can additionally specify revision parameters:
- Command: Commands that the container will run when started. It matches the ENTRYPOINT instruction in the Dockerfile.
- Arguments: Matches the CMD instruction in the Dockerfile. Specify arguments in key = value format. If you do not specify this parameter, the default CMD value from the Docker image will be used.
  
  You can provide multiple arguments to a container. To do this, click Add.
- Working directory: Allows you to change the working directory of a container. It matches the WORKDIR instruction in the Dockerfile. We recommend setting absolute paths to folders.
Click Create revision.

To create a container revision, run this command:

yc serverless container revision deploy \
  --container-name <container_name> \
  --image <Docker_image_URL> \
  --cores 1 \
  --memory 1GB \
  --concurrency 1 \
  --execution-timeout 30s \
  --service-account-id <service_account_ID> \
  --command '<command_1>','<command_2>' \
  --args '<key_1=value_1>','<key_2=value_2>'

Where:

--cores: Number of cores available to the container.
--memory: Required memory. The default value is 128 MB.
--concurrency: Maximum number of concurrent requests to a single container instance. May be in the range between 1 (default) and 16. If the number of requests to a container exceeds the concurrency value, Serverless Containers scales the container up by running its additional instances.

Note

The number of container instances and concurrent container requests in each zone cannot exceed the quota.
--execution-timeout: Timeout. The default value is 3 seconds.
--service-account-id: ID of the service account with permissions to download a Docker image.
--command: Commands the container will run when started. Separate them by commas. It matches the ENTRYPOINT instruction in the Dockerfile.
--args: Arguments matching the CMD instruction in the Dockerfile. Specify them in key = value format separated by commas. If you do not specify this parameter, the default CMD value from the Docker image will be used.

Result:

id: bbajn5q2d74c********
container_id: bba3fva6ka5g********
created_at: "2021-07-09T15:04:55.135Z"
image:
  image_url: cr.yandex/crpd3cicopk7********/test-container:latest
  image_digest: sha256:de8e1dce7ceceeafaae122f7670084a1119c961cd9ea1795eae92bd********
resources:
  memory: "1073741824"
  cores: "1"
execution_timeout: 3s
service_account_id: ajeqnasj95o7********
status: ACTIVE

For more information about the provider resources, see the documentation on the Terraform website or the mirror.

If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

If you don't have Terraform, install it and configure the Yandex Cloud provider.

In Terraform, a new revision is created every time the resource runtime parameters are updated.

To create a revision:

Update the parameters of the yandex_serverless_container resource in the configuration file:

resource "yandex_serverless_container" "test-container" {
  name               = "<container_name>"
  cores              = "<number_of_cores>"
  memory             = "<memory_size>"
  concurrency        = "<concurrent_requests>"
  service_account_id = "<service_account_ID>"
  image {
    url      = "<Docker_image_URL>"
    command  = ["<command_1>","<command_2>"]
    args     = ["<key_1=value_1>","key_2=value_2"]
    work_dir = "<working_directory>"
  }
}

Where:

cores: Number of cores available to the container.
memory: Required memory. The default value is 128 MB.
concurrency: Maximum number of concurrent requests to a single container instance. May be in the range between 1 (default) and 16. If the number of requests to a container exceeds the concurrency value, Serverless Containers scales the container up by running its additional instances.

Note

The number of container instances and concurrent container requests in each zone cannot exceed the quota.
command: Commands the container will run when started. Separate them by commas. It matches the ENTRYPOINT instruction in the Dockerfile.
args: Arguments matching the CMD instruction in the Dockerfile. Specify them in key = value format separated by commas. If you do not specify this parameter, the default CMD value from the Docker image will be used.
work_dir: Allows you to change the working directory of a container. It matches the WORKDIR instruction in the Dockerfile. We recommend setting absolute paths to folders.

For more information about the yandex_serverless_container resource parameters in Terraform, see the relevant provider documentation.

Create resources:
1. In the terminal, change to the folder where you edited the configuration file.
2. Make sure the configuration file is correct using the command:
```
terraform validate
```
  If the configuration is correct, the following message is returned:
```
Success! The configuration is valid.
```
3. Run the command:
```
terraform plan
```
  The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.
4. Apply the configuration changes:
```
terraform apply
```
5. Confirm the changes: type yes in the terminal and press Enter.
This will create the revision. You can check the new revision using the management console or this CLI command:
```
yc serverless container revision list
```

To create a container revision, use the deployRevision REST API method for the Container resource or the ContainerService/DeployRevision gRPC API call.

Invoke the container

After creating the container, you will get the invocation link. Here is how you can retrieve it. Make an HTTPS request by sending an IAM token in the Authorization header:

curl \
  --header "Authorization: Bearer $(yc iam create-token)" \
  https://bba3fva6ka5g********.containers.yandexcloud.net/hello

Result:

Hello!

What's next

Read about service concepts.

Getting started with Serverless Containers

Prepare a Docker image for a containerPrepare a Docker image for a container

App and Dockerfile examplesApp and Dockerfile examples

Add the image to Serverless ContainersAdd the image to Serverless Containers

Create a containerCreate a container

Create a container revisionCreate a container revision

Invoke the containerInvoke the container

What's nextWhat's next

Was the article helpful?

Prepare a Docker image for a container

App and Dockerfile examples

Add the image to Serverless Containers

Create a container

Create a container revision

Invoke the container

What's next