Getting started with the Yandex Cloud SDK
Yandex Cloud SDK is a set of development tools for interfacing with cloud infrastructure.
To illustrate some of the SDK features, we will walk you through creating a Yandex Compute Cloud VM step by step.
To get started with the Yandex Cloud SDK:
- Get your cloud ready.
- Configure the environment.
- Create a configuration file.
- Prepare the script code.
- Run the script to create a VM.
If you no longer need the resources you created, delete them.
See also SDK use cases.
Get your cloud ready
Sign up for Yandex Cloud and create a billing account:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_ACTIVE
status. If you do not have a billing account, create one.
If you have an active billing account, you can go to the cloud page
Learn more about clouds and folders.
Required paid resources
The cost of supporting a VM created with the SDK includes:
- Fee for VM computing resources (see Yandex Compute Cloud pricing).
- Fee for VM disks (see Yandex Compute Cloud pricing).
- Fee for using a dynamic external IP address (see Yandex Virtual Private Cloud pricing).
Create a service account
-
Create a service account.
-
Assign roles to the service account based on the services you want to manage with the Yandex Cloud SDK.
In this tutorial, you will need the compute.admin role to create a VM.
If you are going to use the SDK for .NET, also assign the iam.serviceAccounts.admin role to the service account. You will need this role to get an authorized key.
Prepare the Yandex Cloud CLI
-
Install the Yandex Cloud CLI.
-
Authenticate in the Yandex Cloud CLI as a service account.
With the Yandex Cloud CLI, you will get the Yandex Cloud authentication credentials:
- For Node.js, Go, Python, and Java: IAM token.
- For .NET: Authorized key.
Get the source data
- Get the ID of the folder within which to work with services using the Yandex Cloud SDK.
- Select a suitable image for your VM. Save the image family ID, e.g.,
ubuntu-2204-lts
. - Create a pair of SSH keys to connect to your VM.
Prepare your working directory
-
In the terminal, check the Node.js version using this command:
node -v
The Yandex Cloud SDK supports Node.js version 12 and higher. If Node.js is not installed or you need a newer version, select the appropriate installation option from the Node.js website
. -
Clone the repository containing the Yandex Cloud SDK examples for Node.js
:git clone https://github.com/yandex-cloud-examples/yc-sdk-quickstart-node-js.git
-
Go to your cloned repository and install the dependencies:
cd yc-sdk-quickstart-node-js && npm i
-
In the terminal, check the Go version using this command:
go version
If Go is not installed, select the appropriate installation option from the Go website
. -
Clone the repository containing the Yandex Cloud SDK examples for Go
:git clone https://github.com/yandex-cloud-examples/yc-sdk-quickstart-go.git
-
Go to your cloned repository and install the dependencies:
cd yc-sdk-quickstart-go && go tidy
-
In the terminal, check the Python version using this command for Linux and macOS:
python3 --version
or Windows:
python --version
If Python is not installed, select the appropriate installation option from the Python website
. -
Clone the repository containing the Yandex Cloud SDK examples for Python
:git clone https://github.com/yandex-cloud-examples/yc-sdk-quickstart-python.git
-
Go to your cloned repository and install the dependencies:
cd yc-sdk-quickstart-python && pip install yandexcloud
-
In the terminal, check the Java version using this command:
java --version
If Java is not installed, select the appropriate installation option from the Oracle website
. -
Additionally, install Apache Maven
to build your project. -
Clone the repository containing the Yandex Cloud SDK examples for Java
:git clone https://github.com/yandex-cloud-examples/yc-sdk-quickstart-java.git
-
Got to your cloned repository:
cd yc-sdk-quickstart-java
-
In the terminal, check the .NET version using this command:
dotnet -version
If .NET is not installed, select the appropriate installation option from the Microsoft website
. We recommend installing version 9.0 as it is used in this guide. If you install a different version of .NET, specify it in theYC-test
file. -
Clone the repository containing the Yandex Cloud SDK examples for .NET
:git clone https://github.com/yandex-cloud-examples/yc-sdk-quickstart-dotnet.git
-
In the cloned repository, go to the
yc-sdk-quickstart-dotnet
directory:cd yc-sdk-quickstart-dotnet
Set up a configuration file
Open the config.json
file. It already contains a basic VM configuration, but you can customize it:
{
"folder_id": "<folder_ID>",
"username": "user",
"resources": {
"image": {
"family": "ubuntu-2204-lts",
"folder_family_id": "standard-images"
},
"name": "computer",
"resources_spec": {
"memory": 2147483648,
"cores": 2
},
"boot_disk_spec": {
"auto_delete": true,
"disk_spec": {
"type_id": "network-hdd",
"size": 10737418240
}
},
"zone_id": "ru-central1-d",
"platform_id": "standard-v3",
"subnet_id": "<subnet_ID>"
},
"metadata": {
"ssh-keys": "USERNAME:SSH_PUBLIC_KEY",
"user-data": "#cloud-config\n datasource:\n Ec2:\n strict_id: false\n users:\n - name: USERNAME\n sudo: 'ALL=(ALL) NOPASSWD:ALL'\n shell: /bin/bash\n ssh_authorized_keys:\n - SSH_PUBLIC_KEY"
},
"labels": {
"yc-sdk": "yes"
}
}
Where:
folder_id
: Folder ID.username
: VM user name.family
: Image family ID.folder_family_id
: ID of the folder the images are in; for public images,standard-images
.name
: VM name.memory
: RAM size, in bytes.cores
: Number of vCPUs.auto_delete
: Delete the disk together with the VM.type_id
: VM disk type.size
: Disk size, in bytes.zone_id
: Availability zone you want to put the VM in.platform_id
: Platform ID.subnet_id
: Subnet ID.metadata
: VM metadata.labels
: VM label.
Open the config.json
file. It already contains a basic VM configuration, but you can customize it:
{
"folder_id": "<folder_ID>",
"username": "user",
"resources": {
"image": {
"family": "ubuntu-2204-lts",
"folder_family_id": "standard-images"
},
"name": "computer",
"resources_spec": {
"memory": 2147483648,
"cores": 2
},
"boot_disk_spec": {
"auto_delete": true,
"disk_spec": {
"type_id": "network-hdd",
"size": 10737418240
}
},
"zone_id": "ru-central1-d",
"platform_id": "standard-v3",
"subnet_id": "<subnet_ID>"
},
"metadata": {
"ssh-keys": "USERNAME:SSH_PUBLIC_KEY",
"user-data": "#cloud-config\n datasource:\n Ec2:\n strict_id: false\n users:\n - name: USERNAME\n sudo: 'ALL=(ALL) NOPASSWD:ALL'\n shell: /bin/bash\n ssh_authorized_keys:\n - SSH_PUBLIC_KEY"
},
"labels": {
"yc-sdk": "yes"
}
}
Where:
folder_id
: Folder ID.username
: VM user name.family
: Image family ID.folder_family_id
: ID of the folder the images are in; for public images,standard-images
.name
: VM name.memory
: RAM size, in bytes.cores
: Number of vCPUs.auto_delete
: Delete the disk together with the VM.type_id
: VM disk type.size
: Disk size, in bytes.zone_id
: Availability zone you want to put the VM in.platform_id
: Platform ID.subnet_id
: Subnet ID.metadata
: VM metadata.labels
: VM label.
Open the config.json
file. It already contains a basic VM configuration, but you can customize it:
{
"folder_id": "<folder_ID>",
"username": "user",
"resources": {
"image": {
"family": "ubuntu-2204-lts",
"folder_family_id": "standard-images"
},
"name": "computer",
"resources_spec": {
"memory": 2147483648,
"cores": 2
},
"boot_disk_spec": {
"auto_delete": true,
"disk_spec": {
"type_id": "network-hdd",
"size": 10737418240
}
},
"zone_id": "ru-central1-d",
"platform_id": "standard-v3",
"subnet_id": "<subnet_ID>"
},
"metadata": {
"ssh-keys": "USERNAME:SSH_PUBLIC_KEY",
"user-data": "#cloud-config\n datasource:\n Ec2:\n strict_id: false\n users:\n - name: USERNAME\n sudo: 'ALL=(ALL) NOPASSWD:ALL'\n shell: /bin/bash\n ssh_authorized_keys:\n - SSH_PUBLIC_KEY"
},
"labels": {
"yc-sdk": "yes"
}
}
Where:
folder_id
: Folder ID.username
: VM user name.family
: Image family ID.folder_family_id
: ID of the folder the images are in; for public images,standard-images
.name
: VM name.memory
: RAM size, in bytes.cores
: Number of vCPUs.auto_delete
: Delete the disk together with the VM.type_id
: VM disk type.size
: Disk size, in bytes.zone_id
: Availability zone you want to put the VM in.platform_id
: Platform ID.subnet_id
: Subnet ID.metadata
: VM metadata.labels
: VM label.
Open the config.json
file in the src/main/resources/config
directory. It already has a basic VM configuration installed, and you need to specify folder_id
and subnet_id
. You can also set your custom parameters for other fields:
{
"folder_id": "<folder_ID>",
"username": "user",
"resources": {
"image": {
"family": "ubuntu-2204-lts",
"folder_family_id": "standard-images"
},
"name": "computer",
"resources_spec": {
"memory": 2147483648,
"cores": 2
},
"boot_disk_spec": {
"auto_delete": true,
"disk_spec": {
"type_id": "network-hdd",
"size": 10737418240
}
},
"zone_id": "ru-central1-d",
"platform_id": "standard-v3",
"subnet_id": "<subnet_ID>"
},
"metadata": {
"ssh-keys": "USERNAME:SSH_PUBLIC_KEY",
"user-data": "#cloud-config\n datasource:\n Ec2:\n strict_id: false\n users:\n - name: USERNAME\n sudo: 'ALL=(ALL) NOPASSWD:ALL'\n shell: /bin/bash\n ssh_authorized_keys:\n - SSH_PUBLIC_KEY"
},
"labels": {
"yc-sdk": "yes"
}
}
Where:
folder_id
: Folder ID.username
: VM user name.family
: Image family ID.folder_family_id
: ID of the folder the images are in; for public images,standard-images
.name
: VM name.memory
: RAM size, in bytes.cores
: Number of vCPUs.auto_delete
: Delete the disk together with the VM.type_id
: VM disk type.size
: Disk size, in bytes.zone_id
: Availability zone you want to put the VM in.platform_id
: Platform ID.subnet_id
: Subnet ID.metadata
: VM metadata.labels
: VM label.
Open the config.json
file. It already contains a basic VM configuration, but you can customize it:
{
"folder_id": "<folder_ID>",
"username": "user",
"resources": {
"image": {
"family": "ubuntu-2204-lts",
"folder_family_id": "standard-images"
},
"name": "computer",
"resources_spec": {
"memory": 2147483648,
"cores": 2
},
"boot_disk_spec": {
"auto_delete": true,
"disk_spec": {
"type_id": "network-hdd",
"size": 10737418240
}
},
"zone_id": "ru-central1-d",
"platform_id": "standard-v3",
"subnet_id": "<subnet_ID>"
},
"metadata": {
"ssh-keys": "USERNAME:SSH_PUBLIC_KEY",
"user-data": "#cloud-config\n datasource:\n Ec2:\n strict_id: false\n users:\n - name: USERNAME\n sudo: 'ALL=(ALL) NOPASSWD:ALL'\n shell: /bin/bash\n ssh_authorized_keys:\n - SSH_PUBLIC_KEY"
},
"labels": {
"yc-sdk": "yes"
}
}
Where:
folder_id
: Folder ID.username
: VM user name.family
: Image family ID.folder_family_id
: ID of the folder the images are in; for public images,standard-images
.name
: VM name.memory
: RAM size, in bytes.cores
: Number of vCPUs.auto_delete
: Delete the disk together with the VM.type_id
: VM disk type.size
: Disk size, in bytes.zone_id
: Availability zone you want to put the VM in.platform_id
: Platform ID.subnet_id
: Subnet ID.metadata
: VM metadata.labels
: VM label.
Run the script to create a VM
The project is already configured to create a VM with console commands. See comments in the code to learn more about the steps involved in creating a VM.
Run the index.js
file using this command:
IAM_TOKEN=$(yc iam create-token) \
SSH_PUBLIC_KEY_PATH=./key.pub \
node index.js
Where:
IAM_TOKEN
: IAM token you get using the Yandex Cloud CLI. To learn more about theyc iam create-token
command, see the CLI reference.SSH_PUBLIC_KEY_PATH
: Path to the file with the public SSH key.
Note
Rebooting the system or terminal shell will cause all created environment variables to be lost.
Once you start creating a VM, you will see this text in the terminal:
Running Yandex.Cloud operation. ID: fv4qfujd49fc********
Where ID
is the VM create operation ID.
You can track the operation status in the management console as well as in the Yandex Cloud CLI and API. To learn more, see Viewing operations with Compute Cloud resources.
Once your new VM is created, you will see the following mesage:
Created with id fv4qfujd49fc********
Where id
is the VM ID.
Run the main.go
file using this command:
IAM_TOKEN=$(yc iam create-token) \
SSH_PUBLIC_KEY_PATH=./key.pub \
go run main.go
Where:
IAM_TOKEN
: IAM token you get using the Yandex Cloud CLI. To learn more about theyc iam create-token
command, see the CLI reference.SSH_PUBLIC_KEY_PATH
: Path to the file with the public SSH key.
Note
Rebooting the system or terminal shell will cause all created environment variables to be lost.
Once you start creating a VM, you will see this text in the terminal:
Running Yandex.Cloud operation. ID: fv4qfujd49fc********
Where ID
is the VM create operation ID.
You can track the operation status in the management console as well as in the Yandex Cloud CLI and API. To learn more, see Viewing operations with Compute Cloud resources.
Once your new VM is created, you will see the following mesage:
Created with id fv4qfujd49fc********
Where id
is the VM ID.
Run the script.py
file using this command:
IAM_TOKEN=$(yc iam create-token) \
SSH_PUBLIC_KEY_PATH=./key.pub \
python script.py
Where:
IAM_TOKEN
: IAM token you get using the Yandex Cloud CLI. To learn more about theyc iam create-token
command, see the CLI reference.SSH_PUBLIC_KEY_PATH
: Path to the file with the public SSH key.
Note
Rebooting the system or terminal shell will cause all created environment variables to be lost.
The script runs in stages:
-
Running the script to create a VM. If the script finds no data format errors, you will see the following message:
INFO:yandexcloud._channels:Using endpoints from configuration, IAM iam.api.cloud.yandex.net:443, compute compute.api.cloud.yandex.net:443 INFO:yandexcloud._channels:Using endpoints from configuration, IAM iam.api.cloud.yandex.net:443, compute compute.api.cloud.yandex.net:443 INFO:root:Creating initiated
-
Sending data to the server for validation. If all data is correct, you will see the following message:
INFO:root:Running Yandex.Cloud operation. ID: fv45g3nfq0bn********. Description: Create instance. Created at: 2024-12-19 15:52:59. Created by: ajeutahec4**********. Meta: instance_id: "fv4bi87d50**********". INFO:yandexcloud._channels:Using endpoints from configuration, IAM iam.api.cloud.yandex.net:443, operation operation.api.cloud.yandex.net:443
-
Operation result. After creating a VM, you will get its details:
INFO:root:Done Yandex.Cloud operation. ID: fv45g3nfq0bn********. Response: id: "fv42jgaq946dm8ibkjl6" folder_id: "b1g5hnqtug**********" created_at { seconds: 1734614895 } name: "computer" zone_id: "ru-central1-d" platform_id: "standard-v3" resources { memory: 2147483648 cores: 2 core_fraction: 100 } status: RUNNING metadata_options { gce_http_endpoint: ENABLED aws_v1_http_endpoint: ENABLED gce_http_token: ENABLED aws_v1_http_token: DISABLED } boot_disk { mode: READ_WRITE device_name: "fv4sd8kkspslntd0dpvn" auto_delete: true disk_id: "fv4sd8kkspslntd0dpvn" } network_interfaces { index: "0" mac_address: "d0:0d:29:c1:5a:49" subnet_id: "fl8b5ou7m8sihjbftcfk" primary_v4_address { address: "192.168.0.3" one_to_one_nat { address: "51.250.34.207" ip_version: IPV4 } } } serial_port_settings { ssh_authorization: OS_LOGIN } gpu_settings {} fqdn: "fv42jgaq946dm8ibkjl6.auto.internal" scheduling_policy {} network_settings { type: STANDARD } placement_policy {} hardware_generation { legacy_features { pci_topology: PCI_TOPOLOGY_V1 } }. WARNING: All log messages before absl::InitializeLog() is called are written to STDERR E0000 00:00:1734614936.026768 4332467 init.cc:229] grpc_wait_for_shutdown_with_timeout() timed out.
-
Build your project using this command:
mvn clean package
-
In the root directory of the project, run the code using this command:
IAM_TOKEN=$(yc iam create-token) \ SSH_PUBLIC_KEY_PATH=key.pub \ java -jar target/java-sdk-examples-2.6.4-jar-with-dependencies.jar
Where:
IAM_TOKEN
: IAM token you get using the Yandex Cloud CLI. To learn more about theyc iam create-token
command, see the CLI reference.SSH_PUBLIC_KEY_PATH
: Path to the file with the public SSH key.
Note
Rebooting the system or terminal shell will cause all created environment variables to be lost.
Once you start creating a VM, you will see this text in the terminal:
Running Yandex.Cloud operation. ID: fv4qfujd49fc********
Where
ID
is the VM create operation ID.You can track the operation status in the management console as well as in the Yandex Cloud CLI and API. To learn more, see Viewing operations with Compute Cloud resources.
Once your new VM is created, you will see the following mesage:
Created with id fv4qfujd49fc********
Where
id
is the VM ID.
In the root directory of the project, run the code using this command:
yc iam key create \
--output key.json \
--service-account-name <service_account_name> && \
AUTH_KEY=$(<key.json) && \
rm key.json && \
SSH_PUBLIC_KEY_PATH=~/key.pub \
dotnet run
This command consists of the following parts:
yc iam key create
: Command to get an authorized key, where:--output
: Path to the file for saving the authorized key in JSON format.--service-account-name
: Name of the service account you are creating the key for.
AUTH_KEY=$(<key.json>)
: Reading the authorized key file and placing the key contents in theAUTH_KEY
variable.rm key.json
: Deleting the authorized key file. You can skip this part of the command if you plan to reuse the authorized key.SSH_PUBLIC_KEY_PATH=~/key.pub
: Providing the path to your public SSH key file to theSSH_PUBLIC_KEY_PATH
environment variable.dotnet run
: Running the script.
Note
Rebooting the system or terminal shell will cause all created environment variables to be lost.
Once you start creating a VM, you will see this text in the terminal:
Running Yandex.Cloud operation. ID: fv4qfujd49fc********
Where ID
is the VM create operation ID.
You can track the operation status in the management console as well as in the Yandex Cloud CLI and API. To learn more, see Viewing operations with Compute Cloud resources.
You can check the new VM in the management consoleyc-sdk:yes
label.
How to delete the resources you created
To stop paying for the resources you created, delete your VM from Compute Cloud.