Getting started with Terraform
To create your first infrastructure in Nebius AI using Terraform:
- Prepare your cloud.
- Install Terraform.
- Get the authentication data
- Create a Terraform configuration file.
- Configure a provider.
- Prepare an infrastructure plan.
- Check and format your configuration files.
- Create resources.
If you no longer need the resources, delete them.
Prepare your cloud
Go to the management console
Install Terraform
Use one of the following methods:
-
Download a Terraform distribution
and install it by following the instructions . -
Install Terraform using the Chocolatey
package manager and the command below:choco install terraform
Download a Terraform distribution
Use one of the following methods:
-
Download a Terraform distribution
and install it by following the instructions . -
Install Terraform using the Homebrew
package manager and the command below:brew install terraform
For more ways of installing Terraform, see the HashiCorp documentation
Get the authentication credentials and assign the roles
Use a service account to manage the Nebius AI infrastructure using Terraform. It will help you to flexibly configure access rights for resources.
You can also access Terraform from your Google account, or a federated account, but this method is less secure. For more information, see the end of this section.
-
If you do not have the Nebius AI command line interface, install it.
-
If you do not have a service account, create one:
Management consoleCLI-
In the management console
, select a folder where you want to create a service account. -
In the Service accounts tab, click Create service account.
-
Enter the name of the service account.
The name format requirements are as follows:
- The length can be from 3 to 63 characters.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter. The last character can't be a hyphen.
-
Click Create.
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.Run the command to create a service account:
ncp iam service-account create --name <service_account_name>
Where
name
is the name of the service account in the format:- The length can be from 3 to 63 characters.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter. The last character can't be a hyphen.
Result:
id: ajehr0to1g8bh0la8c8r folder_id: b1gv87ssvu497lpgjh5o created_at: "2022-09-14T09:03:11.665153755Z" name: sa-terraform
-
-
Add the service account to the
editors
group. -
Set up the CLI profile to execute operations on behalf of the service account:
CLI-
Create an authorized key for your service account and save the file:
ncp iam key create \ --service-account-id <service_account_ID> \ --folder-name <name_of_folder_with_service_account> \ --output key.json
Where:
service-account-id
: ID of your service account.folder-name
: Name of the folder the service account was created in.output
: Name of the file with the authorized key.
Result:
id: aje8nn871qo4a8bbopvb service_account_id: ajehr0to1g8bh0la8c8r created_at: "2022-09-14T09:11:43.479156798Z" key_algorithm: RSA_2048
-
Set up the CLI profile to execute operations on behalf of the service account. Name the profile:
ncp config profile create <profile_name>
Result:
Profile 'sa-terraform' created and activated
-
Set the profile configuration:
ncp config set service-account-key key.json ncp config set cloud-id <cloud_ID> ncp config set folder-id <folder_ID>
Where:
service-account-key
: A file including the service account's authorized key.cloud-id
: ID of the cloud.folder-id
: ID of the folder.
-
-
Add the credentials to the environment variables:
BashPowerShellexport NCP_TOKEN=$(ncp iam create-token) export NCP_CLOUD_ID=$(ncp config get cloud-id) export NCP_FOLDER_ID=$(ncp config get folder-id)
Where:
NCP_TOKEN
: IAM token.NCP_CLOUD_ID
: Cloud ID.NCP_FOLDER_ID
: Folder ID.
$Env:NCP_TOKEN=$(ncp iam create-token) $Env:NCP_CLOUD_ID=$(ncp config get cloud-id) $Env:NCP_FOLDER_ID=$(ncp config get folder-id)
Where:
NCP_TOKEN
: IAM token.NCP_CLOUD_ID
: Cloud ID.NCP_FOLDER_ID
: Folder ID.
Note
The IAM token lifetime doesn't exceed 12 hours, but we recommend requesting the token more often, like once per hour.
Warning
Managing resources on behalf of the user's Google account or a federated account is less secure than on behalf of the service account.
If you don't have the Nebius AI 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.
If you use a federated account, log in to CLI on behalf of the federated user.
Add the credentials to the environment variables:
export NCP_TOKEN=$(ncp iam create-token)
export NCP_CLOUD_ID=$(ncp config get cloud-id)
export NCP_FOLDER_ID=$(ncp config get folder-id)
Where:
NCP_TOKEN
: IAM token.NCP_CLOUD_ID
: Cloud ID.NCP_FOLDER_ID
: Folder ID.
$Env:NCP_TOKEN=$(ncp iam create-token)
$Env:NCP_CLOUD_ID=$(ncp config get cloud-id)
$Env:NCP_FOLDER_ID=$(ncp config get folder-id)
Where:
NCP_TOKEN
: IAM token.NCP_CLOUD_ID
: Cloud ID.NCP_FOLDER_ID
: Folder ID.
Note
The IAM token lifetime doesn't exceed 12 hours, but we recommend requesting the token more often, like once per hour.
Create a Terraform configuration file
-
Create a directory with any name, for example,
cloud-terraform
. It stores the configuration files and saved states for Terraform and your infrastructure.Warning
Each configuration must be in a separate directory.
-
Create a configuration file with the
.tf
extension in this directory, such asmain.tf
.
Configure a provider
Note
These settings apply to Terraform 0.13
and higher. It's recommended to use the latest stable version of Terraform.
-
Add the following sections at the top of the
.tf
configuration file:terraform { required_providers { nebius = { source = "terraform-registry.storage.ai.nebius.cloud/nebius/nebius" version = ">= 0.6.0" # Optional } } required_version = ">= 0.13" } provider "nebius" { zone = "<default availability zone>" }
Where:
-
source
: Provider's global source address . -
version
: Provider's version. Optional parameter. -
required_version
: The minimum version of Terraform the provider is compatible with. -
provider
: The provider name. -
endpoint
: Domain name and port for requests to the Nebius AI API:api.ai.nebius.cloud:443
. -
storage_endpoint
: Endpoint for managing Object Storage resources:storage.ai.nebius.cloud
.
-
-
Run the
terraform init
command in the folder containing the.tf
configuration file. This command initializes the providers specified in the configuration files and allows you to work with the provider resources and data sources.
If the provider installation failed, create a support request indicating the provider name and version.
Prepare an infrastructure plan
Using Terraform in Nebius AI, you can create cloud resources of any type, such as VMs, disks, and images. For more information about the resources you can create with Terraform, see the provider documentation
To create a resource, specify a set of required and optional parameters that define the resource properties. Such resource descriptions make up an infrastructure plan.
The plan includes creating two VMs: terraform1
and terraform2
, as well as a cloud network called network-1
with a subnet named subnet-1
.
Resource names must meet the following requirements:
- The length can be from 3 to 63 characters.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter. The last character can't be a hyphen.
The VMs will have different vCPU and memory configurations: 2 vCPUs and 2 GB of RAM for terraform1
and 4 vCPUs and 4 GB of RAM for terraform2
. The VMs will be automatically assigned public and private IP addresses from the 192.168.10.0/24
range in subnet-1
located in the eu-north1-c
availability zone and belonging to the network-1
cloud network. The VMs will run Ubuntu OS and host the public part of the key to enable SSH access to the VMs.
In the VM configuration, you will need to specify the boot disk image ID. You can get a list of available public images using this CLI command:
ncp compute image list --folder-id standard-images
To access the VMs over SSH, generate an SSH key pair and include the public key to the VM in the ssh-keys
parameter in the metadata
section.
Resource configurations are specified immediately after the provider's configuration:
terraform {
required_providers {
nebius = {
source = "terraform-registry.storage.ai.nebius.cloud/nebius/nebius"
}
}
}
provider "nebius" {
zone = "<default availability zone>"
}
resource "nebius_compute_instance" "vm-1" {
name = "terraform1"
}
According to the plan, the following resources are created:
Network-1
cloud network with a subnet namedsubnet-1
in theeu-north1-c
availability zone.- Two Linux VMs:
terraform1
(2 cores and 2 GB of RAM) andterraform2
(4 cores and 4 GB of RAM). The VMs are automatically assigned public and private IP addresses from the192.168.10.0/24
range insubnet-1
.
-
Generate an SSH key pair to connect to your VM over SSH.
-
Describe the resource parameters in the
main.tf
file:- In the
ssh-keys
parameter undermetadata
, specify the path to the public part of the SSH key. - In the
image_id
parameter, set the boot disk image ID.
main.tf file<provider settings> data "nebius_compute_image" "ubuntu-2204" { family = "ubuntu-2204-lts" } resource "nebius_compute_instance" "vm-1" { name = "terraform1" resources { cores = 2 memory = 2 } boot_disk { initialize_params { image_id = data.nebius_compute_image.ubuntu-2204.id } } network_interface { subnet_id = nebius_vpc_subnet.subnet-1.id nat = true } metadata = { ssh-keys = "ubuntu:${file("~/.ssh/id_ed25519.pub")}" } } resource "nebius_compute_instance" "vm-2" { name = "terraform2" resources { cores = 4 memory = 4 } boot_disk { initialize_params { image_id = data.nebius_compute_image.ubuntu-2204.id } } network_interface { subnet_id = nebius_vpc_subnet.subnet-1.id nat = true } metadata = { ssh-keys = "ubuntu:${file("~/.ssh/id_ed25519.pub")}" } } resource "nebius_vpc_network" "network-1" { name = "network1" } resource "nebius_vpc_subnet" "subnet-1" { name = "subnet1" zone = "eu-north1-c" network_id = nebius_vpc_network.network-1.id v4_cidr_blocks = ["192.168.10.0/24"] } output "internal_ip_address_vm_1" { value = nebius_compute_instance.vm-1.network_interface.0.ip_address } output "internal_ip_address_vm_2" { value = nebius_compute_instance.vm-2.network_interface.0.ip_address } output "external_ip_address_vm_1" { value = nebius_compute_instance.vm-1.network_interface.0.nat_ip_address } output "external_ip_address_vm_2" { value = nebius_compute_instance.vm-2.network_interface.0.nat_ip_address }
- In the
Create users
To add a user to a VM being created, under metadata
, include the user-data
parameter with the user metadata. To do this:
-
Create a UTF-8 encoded text file containing the metadata, for example:
#cloud-config users: - name: <username> groups: sudo shell: /bin/bash sudo: 'ALL=(ALL) NOPASSWD:ALL' ssh-authorized-keys: - <public_SSH_key_1> - <public_SSH_key_2> - ...
Where:
-
name
: VM username. -
ssh-authorized-keys
(orssh_authorized_keys
): List of public SSH keys for VM access.Sample key:
ssh-ed25519 AAAAB3Nza......Pu00jRN user@desktop
.
-
-
In the
main.tf
file, replacessh-keys
with theuser-data
parameter and specify the metadata file path:metadata = { user-data = "${file("<file path>/meta.txt")}" }
For more information about working with metadata, see VM instance metadata.
Check and format the configuration files
-
Check the configuration using the command:
terraform validate
If the configuration is valid, the following message is returned:
Success! The configuration is valid.
-
Format the configuration files in the current folder and subfolders:
terraform fmt
Result:
main.tf variables.tf
Create resources
-
To test the configuration, run the command:
terraform plan
The terminal will display a list of resources with parameters. This is a test step. No resources are created. If there are errors in the configuration, Terraform points them out.
Alert
You're charged for all resources created using Terraform. Check the plan carefully.
-
To create resources, run the command:
terraform apply
-
Confirm the resource creation: type
yes
in the terminal and press Enter.Terraform will create all the required resources and the terminal will display the IP addresses of the created VMs. You can check resource availability and their settings in the management console
.
How to delete the resources you created
To delete the resources created with Terraform:
-
Go to the the directory with the configuration files.
-
Run the command:
terraform destroy
Alert
Terraform deletes all the resources that you created in the current configuration, such as clusters, networks, subnets, and VMs.
After the command is executed, the terminal will display a list of resources to be deleted.
-
Type the word
yes
, then press Enter.
You can use the management console