Getting started with Serverless Containers
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.
Application and Dockerfile examples
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
-
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
For more information about the provider resources, see the documentation on the Terraform
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
: Docker image URL in Yandex Container Registry.
Here is an example of the configuration file structure:
provider "yandex" { token = "<OAuth>" 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 in Terraform, see the provider documentation . -
-
Make sure the configuration files are valid.
-
In the command line, go to the directory where you created the configuration file.
-
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.
-
If the configuration does not contain any errors, run this command:
terraform apply
-
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 configuration 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
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 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.
- Specify the revision parameters.
- 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>
Where:
-
--cores
: Number of cores available for 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 theconcurrency
value, Yandex 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 authorized to download an image.
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
Terraform
For more information about the provider resources, see the documentation on the Terraform
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
yandex_serverless_container
resource runtime parameters in the configuration file:provider "yandex" { token = "<OAuth>" 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 in Terraform, see the provider documentation . -
Make sure the configuration files are valid.
-
In the command line, navigate to the folder where the configuration file was created.
-
Run a check using this command:
terraform plan
If the configuration is described correctly, the terminal will display a list of resources being created or updated and their parameters. If the configuration contains any errors, Terraform will point them out.
-
-
If the configuration does not contain any errors, run this command:
terraform apply
-
Confirm the resource creation or update: 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 -H "Authorization: Bearer $(yc iam create-token)" https://bba3fva6ka5g********.containers.yandexcloud.net/hello
Result:
Hello!
What's next
- Read about service concepts.