Using Yandex Cloud modules in Terraform
- Prepare your cloud
- Install Terraform
- Get the authentication credentials
- Create a Terraform configuration file
- Configure a provider
- Enable the virtual network management module
- Enable the Managed Service for Kubernetes module
- Check and format the configuration files
- Create resources
- How to delete the resources you created
- See also
Yandex Cloud provides a
This page explains how to enable the modules and use them to create a test infrastructure with a cloud network, three Yandex Virtual Private Cloud subnets, and a Yandex Managed Service for Kubernetes cluster.
To create your first infrastructure in Yandex Cloud using Terraform:
- Prepare your cloud.
- Install Terraform.
- Get the authentication data
- Create a Terraform configuration file.
- Configure a provider.
If you no longer need the resources, delete them.
Prepare your cloud
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 support for the infrastructure deployed through Terraform in this tutorial includes:
- Fee for a Managed Service for Kubernetes regional master (see Managed Service for Kubernetes pricing).
- Fee for continuously running VMs in the Managed Service for Kubernetes node group (see Yandex Compute Cloud pricing).
- Fee for using a dynamic public IP address (see Virtual Private Cloud pricing).
Install Terraform
From a mirror
Alert
The mirror may be unavailable.
You can download a Terraform distribution for your platform from a mirrorPATH
variable:
export PATH=$PATH:/path/to/terraform
From the HashiCorp website
Use one of the following methods:
-
Download the Terraform distribution
and follow this guide to install it. -
Install Terraform using the Chocolatey
package manager and the command below:choco install terraform
Download the Terraform distribution
Use one of the following methods:
-
Download the Terraform distribution
and follow this guide to install it. -
Install Terraform using the Homebrew
package manager and the command below:brew install terraform
Get the authentication credentials
Use a service account to manage the Yandex Cloud infrastructure using Terraform. It will help you flexibly configure access permissions to resources.
You can also use Terraform under your Yandex 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 Yandex Cloud command line interface, install it.
-
If you do not have a service account, create one:
Management consoleCLIAPI-
In the management console
, select the folder where you want to create a service account. -
In the Service accounts tab, click Create service account.
-
Enter a name for the service account.
The name format 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.
-
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:
yc iam service-account create --name <service_account_name>
Where
name
is the service account name in the following format:- 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.
Result:
id: ajehr0to1g8b******** folder_id: b1gv87ssvu49******** created_at: "2022-09-14T09:03:11.665153755Z" name: sa-terraform
To create a service account, use the ServiceAccountService/Create gRPC API call or the create REST API method for the
ServiceAccount
resource. -
-
Assign, to the service account, the following roles needed to manage Yandex Cloud resources:
You can assign roles to a service account for any resources in any cloud if these resources belong to the same organization as the service account. You can also assign roles to a service account for the organization.
Management consoleCLIAPITo assign to a service account a role for the folder:
- In the management console
, select the appropriate folder. - Go to the Access bindings tab.
- Click Configure access.
- In the window that opens, select Service accounts.
- Select a service account from the list or use the search.
- Click
Add role and select the role in the folder. - Click Save.
-
Find out the ID of the service account (the
ID
column) you want to assign the role to:yc iam service-account list
Result:
+----------------------+--------------+ | ID | NAME | +----------------------+--------------+ | aje6ij7qvdhb******** | sa-terraform | +----------------------+--------------+
-
Assign the role for the resource to the service account:
yc <service-name> <resource> add-access-binding <resource-name>|<resource-id> \ --role <role-id> \ --subject serviceAccount:<service-account-id>
Where:
<service-name>
: Name of the service for whose resource you want to assign the role, e.g.,resource-manager
.<resource>
: Resource category, e.g.,cloud
to assign a role for the entire cloud, orfolder
to assign a role for a folder.<resource-name>
: Resource name. You can specify a resource by its name or ID (cloud or folder name).<resource-id>
: Resource ID (cloud or folder ID).<role-id>
: Role being assigned, e.g.,resource-manager.clouds.owner
.<service-account-id>
: ID of the service account getting the role.
Example:
yc resource-manager folder add-access-binding **********9n9hi2qu --role editor --subject serviceAccount:**********qhi2qu
Result:
done (1s)
To assign the service account a role for a cloud or folder, use the
updateAccessBindings
REST API method for the Cloud or Folder resource:-
Select a role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.
-
Get the ID of the service accounts folder.
-
Get an IAM token required for authorization in the Yandex Cloud API.
-
Get a list of folder service accounts to find out their IDs:
export FOLDER_ID=b1gvmob95yys******** export IAM_TOKEN=CggaATEVAgA... curl -H "Authorization: Bearer ${IAM_TOKEN}" \ "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"
Result:
{ "serviceAccounts": [ { "id": "ajebqtreob2d********", "folderId": "b1gvmob95yys********", "createdAt": "2018-10-18T13:42:40Z", "name": "my-robot", "description": "my description" } ] }
-
Create the request body, for example, in the
body.json
file. Set theaction
property toADD
and theroleId
property to the appropriate role, such aseditor
, and specify theserviceAccount
type and service account ID in thesubject
property:body.json:
{ "accessBindingDeltas": [{ "action": "ADD", "accessBinding": { "roleId": "editor", "subject": { "id": "ajebqtreob2d********", "type": "serviceAccount" } } }] }
-
Assign a role to a service account. For example, for a folder with the
b1gvmob95yys********
ID:export FOLDER_ID=b1gvmob95yys******** export IAM_TOKEN=CggaAT******** curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${IAM_TOKEN}" \ -d '@body.json' \ "https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/${FOLDER_ID}:updateAccessBindings"
- In the management console
-
Set up the CLI profile to run operations on behalf of the service account:
CLI-
Create an authorized key for your service account and save the file:
yc iam key create \ --service-account-id <service_account_ID> \ --folder-name <service_account_folder_name> \ --output key.json
Where:
service-account-id
: Service account ID.folder-name
: Name of the folder in which the service account was created.output
: Name of the file with the authorized key.
Result:
id: aje8nn871qo4******** service_account_id: ajehr0to1g8******** created_at: "2022-09-14T09:11:43.479156798Z" key_algorithm: RSA_2048
-
Create a CLI profile to run operations on behalf of the service account. Name the profile:
yc config profile create <profile_name>
Result:
Profile 'sa-terraform' created and activated
-
Set the profile configuration:
yc config set service-account-key key.json yc config set cloud-id <cloud_ID> yc config set folder-id <folder_ID>
Where:
-
-
Add the credentials to the environment variables:
BashPowerShellexport YC_TOKEN=$(yc iam create-token) export YC_CLOUD_ID=$(yc config get cloud-id) export YC_FOLDER_ID=$(yc config get folder-id)
Where:
YC_TOKEN
: IAM token.YC_CLOUD_ID
: Cloud ID.YC_FOLDER_ID
: Folder ID.
$Env:YC_TOKEN=$(yc iam create-token) $Env:YC_CLOUD_ID=$(yc config get cloud-id) $Env:YC_FOLDER_ID=$(yc config get folder-id)
Where:
YC_TOKEN
: IAM token.YC_CLOUD_ID
: Cloud ID.YC_FOLDER_ID
: Folder ID.
Note
The IAM token lifetime does not exceed 12 hours; however, we recommend requesting it more often, such as once per hour.
Managing resources on behalf of a Yandex account or a federated account
Warning
Managing resources under a user's Yandex account or federated account is less secure than under a service account.
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.
If you use a federated account, authenticate with the CLI on behalf of the federated user.
Add the credentials to the environment variables:
export YC_TOKEN=$(yc iam create-token)
export YC_CLOUD_ID=$(yc config get cloud-id)
export YC_FOLDER_ID=$(yc config get folder-id)
Where:
YC_TOKEN
: IAM token.YC_CLOUD_ID
: Cloud ID.YC_FOLDER_ID
: Folder ID.
$Env:YC_TOKEN=$(yc iam create-token)
$Env:YC_CLOUD_ID=$(yc config get cloud-id)
$Env:YC_FOLDER_ID=$(yc config get folder-id)
Where:
YC_TOKEN
: IAM token.YC_CLOUD_ID
: Cloud ID.YC_FOLDER_ID
: Folder ID.
Note
The IAM token lifetime does not exceed 12 hours; however, we recommend requesting it more often, such as once per hour.
Create a Terraform configuration file
-
Create a new 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. We recommend using the latest stable version of Terraform.
-
If you previously configured a provider from the HashiCorp registry, save its settings:
Linux/macOSWindowsmv ~/.terraformrc ~/.terraformrc.old
mv $env:APPDATA/terraform.rc $env:APPDATA/terraform.rc.old
-
Specify the source the provider will be installed from.
Linux/macOSWindowsOpen the Terraform CLI configuration file:
nano ~/.terraformrc
Note
The
.terraformrc
file must be in the user's home root folder, e.g.,/home/user/
or/User/user/
.Open the Terraform CLI configuration file named
terraform.rc
in your user's%APPDATA%
folder.To find out the absolute path to the
%APPDATA%
folder, run theecho %APPDATA%
command for cmd or the$env:APPDATA
command for PowerShell.Add the following section to the file:
provider_installation { network_mirror { url = "https://terraform-mirror.yandexcloud.net/" include = ["registry.terraform.io/*/*"] } direct { exclude = ["registry.terraform.io/*/*"] } }
For more information about setting up mirrors, see the documentation
. -
Add the following sections at the top of the
.tf
configuration file:terraform { required_providers { yandex = { source = "yandex-cloud/yandex" } } required_version = ">= 0.13" } provider "yandex" { zone = "<default_availability_zone>" }
Where:
source
: Provider's global source address .required_version
: Minimum Terraform version the provider is compatible with.provider
: Provider name.zone
: Availability zone where all cloud resources will be created by default.
-
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
If you used the .terraform.lock.hcl
file, prior to the initialization, run the terraform providers lock
command specifying the URL of the mirror to upload the provider from and the platforms the configuration will run on:
terraform providers lock -net-mirror=https://terraform-mirror.yandexcloud.net -platform=<platform_1_name> -platform=<platform_2_name> yandex-cloud/yandex
Where:
-net-mirror
: Address of the mirror to upload the provider from.-platform
: Platforms to use the configuration on. The possible values include:windows_amd64
: 64-bit Windowslinux_amd64
: 64-bit Linuxdarwin_arm64
: 64-bit macOS
If you used the Terraform modules, first run terraform init
, then delete the lock file. After that, run the terraform providers lock
command.
For more information about the terraform providers lock
command, see the Terraform documentation
Enable the virtual network management module
Add the terraform-yc-vpc
module to the configuration. You can use this module to manage your cloud network infrastructure, including networks, subnets, gateways, and other Virtual Private Cloud objects. Create a test network with three subnets in different availability zones:
module "yc-vpc" {
source = "github.com/terraform-yc-modules/terraform-yc-vpc.git"
network_name = "test-module-network"
network_description = "Test network created with module"
private_subnets = [{
name = "subnet-1"
zone = "ru-central1-a"
v4_cidr_blocks = ["10.10.0.0/24"]
},
{
name = "subnet-2"
zone = "ru-central1-b"
v4_cidr_blocks = ["10.11.0.0/24"]
},
{
name = "subnet-3"
zone = "ru-central1-d"
v4_cidr_blocks = ["10.12.0.0/24"]
}
]
}
Enable the Managed Service for Kubernetes module
Add the terraform-yc-vpc
module to the configuration and the Managed Service for Kubernetes cluster configuration with a regional master and two node groups:
module "kube" {
source = "github.com/terraform-yc-modules/terraform-yc-kubernetes.git"
network_id = "${module.yc-vpc.vpc_id}"
master_locations = [
for s in module.yc-vpc.private_subnets:
{
zone = s.zone,
subnet_id = s.subnet_id
}
]
master_maintenance_windows = [
{
day = "monday"
start_time = "23:00"
duration = "3h"
}
]
node_groups = {
"yc-k8s-ng-01" = {
description = "Kubernetes nodes group 01"
fixed_scale = {
size = 3
}
node_labels = {
role = "worker-01"
environment = "testing"
}
},
"yc-k8s-ng-02" = {
description = "Kubernetes nodes group 02"
auto_scale = {
min = 2
max = 4
initial = 2
}
node_labels = {
role = "worker-02"
environment = "dev"
}
max_expansion = 1
max_unavailable = 1
}
}
}
Check and format the configuration files
-
Check the configuration using this command:
terraform validate
If the configuration is valid, you will get this message:
Success! The configuration is valid.
-
Format the configuration files in the current folder and subfolders:
terraform fmt
Result:
main.tf variables.tf
Create resources
-
After checking the configuration, run the command:
terraform plan
The terminal will display a list of resources with parameters. This is a test step; no resources will be created. If the configuration contains any errors, Terraform will point them out.
Alert
You will be charged for all the resources created with Terraform. Check the pricing plan carefully.
-
To create resources, run the command:
terraform apply
-
Confirm creating the resources: 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 the new resources and their configuration using the management console
.
How to delete the resources you created
To delete the resources created with Terraform:
-
Run this command:
terraform destroy
Alert
After the command is executed, the terminal will display a list of resources to be deleted.
-
Type
yes
and press Enter.