Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex Compute Cloud
    • All guides
      • Configuring metadata service parameters
      • Getting VM instance metadata
      • Getting a VM instance identity document
      • Changing VM instance metadata
      • Creating a VM with a custom configuration script
      • Creating a VM with metadata from environment variables
      • Creating a VM instance with access to a Yandex Lockbox secret
    • Viewing operations with resources
  • Yandex Container Solution
  • Access management
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes
  1. Step-by-step guides
  2. Creating a VM
  3. Creating a VM instance with access to a Yandex Lockbox secret

Creating a VM instance with access to a Yandex Lockbox secret

Written by
Yandex Cloud
Improved by
Danila N.
Updated at May 5, 2025

You can use the metadata service to provide the ID of a Yandex Lockbox secret to a VM and then get the value of that secret from inside the VM using the IAM token of the service account linked to the VM.

Just like other user data, Yandex Lockbox secrets are provided in the user-data key. You can provide metadata to the user-data folder both when creating and updating a VM.

To provide a Yandex Lockbox secret to a VM via metadata:

  1. Create a Yandex Lockbox secret.

  2. Create a service account and assign the lockbox.payloadViewer role to it.

  3. Create a file named metadata.yaml and paste into it the following metadata configuration for the new VM:

    metadata.yaml

    #cloud-config
    
    datasource:
      Ec2:
        strict_id: false
      secrets:
        my_secret: <secret_ID>
    ssh_pwauth: no
    users:
      - name: <username>
        sudo: ALL=(ALL) NOPASSWD:ALL
        shell: /bin/bash
        ssh-authorized-keys:
          - "<user_public_SSH_key>"
    packages:
      - jq
      - yq
    

    Where:

    • my_secret: ID of the secret you created.

      Warning

      Provide only the IDs of your secrets to the user-data folder, not their values.

    • name: Name of the local user to create on the VM, e.g., admin.

    • ssh-authorized-keys: Public SSH key of the new VM user.

  4. Create a virtual machine:

    Management console
    CLI
    Terraform
    API
    1. In the management console, select the folder containing your secret and service account.

    2. From the list of services, select Compute Cloud.

    3. In the left-hand panel, select Virtual machines.

    4. Click Create virtual machine.

    5. Under Boot disk image, select the Ubuntu 24.04 LTS image.

    6. Under Location, select an availability zone the VM will reside in.

    7. Under Network settings, in the Subnet field, enter the ID of a subnet in the new VM's availability zone or select a cloud network from the list.

    8. Under Access, select SSH key and specify the VM access credentials:

      • Enter the VM user name in the Login field,
      • In the SSH key field, select the SSH key saved in your organization user profile.

        If there are no saved SSH keys in your profile, or you want to add a new key:

        • Click Add key.
        • Enter a name for the SSH key.
        • Upload or paste the contents of the public key file. You need to create a key pair for the SSH connection to a VM yourself.
        • Click Add.

        The SSH key will be added to your organization user profile.

        If users cannot add SSH keys to their profiles in the organization, the added public SSH key will only be saved to the user profile of the VM being created.

    9. Under General information, enter a name for your VM:

      • It must be from 2 to 63 characters long.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • It must start with a letter and cannot end with a hyphen.
    10. Under Additional, select the service account you created earlier.

    11. Under Metadata:

      • In the Key field, specify user-data.
      • In the Value field, paste the contents of the metadata.yaml configuration file you created earlier.
    12. Click Create VM.

    If you do not have the Yandex Cloud CLI yet, install and initialize it.

    The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

    Run this command:

    yc compute instance create \
      --name my-vm \
      --hostname <host_name> \
      --zone <availability_zone> \
      --create-boot-disk image-folder-id=standard-images,image-family=ubuntu-2404-lts-oslogin \
      --network-interface subnet-name=<subnet_name>,ipv4-address=auto,nat-ip-version=ipv4 \
      --metadata-from-file user-data="<path_to_configuration_file>" \
      --service-account-id <service_account_ID>
    

    Where:

    • --name: Name of the new VM, e.g., my-vm.

    • --hostname: Host name for the new VM. This is an optional parameter. If omitted, the VM ID will be used as the host name.

    • --zone: Availability zone the new VM will reside in.

    • --network-interface: Network interface settings for the new VM:

      • subnet-name: Name of the subnet in the availability zone specified in the --zone parameter.
    • --metadata-from-file: The user-data key with the path to the cloud-config YAML configuration file for value, e.g., --metadata-from-file user-data="/home/user/metadata.yaml".

    • service-account-id: ID of the service account with the lockbox.payloadViewer role.

    Result
    done (31s)
    id: epde2t9aovjm********
    folder_id: b1gt6g8ht345********
    created_at: "2025-02-04T18:18:58Z"
    name: my-vm
    zone_id: ru-central1-b
    platform_id: standard-v2
    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: epd27gmf2vu2********
      auto_delete: true
      disk_id: epd27gmf2vu2********
    network_interfaces:
      - index: "0"
        mac_address: d0:0d:e1:75:2a:c7
        subnet_id: e2lqsms4cdl3********
        primary_v4_address:
          address: 192.168.15.25
          one_to_one_nat:
            address: 51.***.***.93
            ip_version: IPV4
    serial_port_settings:
      ssh_authorization: OS_LOGIN
    gpu_settings: {}
    fqdn: my-vm.ru-central1.internal
    scheduling_policy: {}
    service_account_id: ajegtlf2q28a********
    network_settings:
      type: STANDARD
    placement_policy: {}
    hardware_generation:
      legacy_features:
        pci_topology: PCI_TOPOLOGY_V1
    

    If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

    1. In the configuration file, define the parameters of the resources you want to create:

      # Creating a boot disk for the VM
      
      resource "yandex_compute_disk" "boot-disk" {
        type     = "network-ssd"
        zone     = "<availability_zone>"
        size     = "20"
        image_id = "fd8bpal18cm4kprpjc2m"
      }
      
      # Creating a VM instance
      
      resource "yandex_compute_instance" "my-vm" {
        name               = "<VM_name>"
        platform_id        = "standard-v2"
        zone               = "<availability_zone>"
        service_account_id = "<service_account_ID>"
      
        resources {
          cores  = "2"
          memory = "4"
        }
      
        boot_disk {
          disk_id = yandex_compute_disk.boot-disk.id
        }
      
        network_interface {
          subnet_id          = "<subnet_ID>"
          nat                = true
          security_group_ids = ["<security_group_ID>"]
        }
      
        metadata = {
          user-data = "${file("<path_to_configuration_file>")}"
        }
      }
      

      Where:

      • zone: Availability zone the VM and disk will reside in.
      • service_account_id: ID of the previously created service account with the lockbox.payloadViewer role.
      • name: Name of the new VM, e.g., my-vm.
      • subnet_id: ID of the subnet in the availability zone specified in the zone parameter.
      • security_group_ids: Security group ID.
      • user-data: Path to the metadata.yaml configuration file you created earlier.

      For more information about the resources being created, see the relevant TF provider articles.

    2. Create the 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 all the resources you need in the specified folder. You can check the new resources and their settings using the management console.

    Use the create REST API method for the Instance resource or the InstanceService/Create gRPC API call.

  5. Connect to the new VM over SSH. In the VM terminal:

    1. Get the IAM token of the service account linked to the VM and save that token to the YC_TOKEN variable. To do this, send the following request to the computeMetadata folder in the metadata service:

      export YC_TOKEN=$(curl -sf -H Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | jq -r .access_token)
      
    2. Get the secret ID you provided to the user-data folder in the metadata service when creating the VM.

      export my_secret_id=$(curl -sf -H Metadata-Flavor:Google 169.254.169.254/latest/user-data | yq .datasource.secrets.my_secret | tr -d \")
      
    3. Get the secret value and save it to the my_secret_value variable. To do this, send the following request to the Yandex Lockbox API:

      export my_secret_value=$(curl -sf -H "Authorization: Bearer $YC_TOKEN" "https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/${my_secret_id}/payload" | jq -r .entries[0].textValue)
      echo $my_secret_value
      

      Result:

      admin@my-vm:~$ echo $my_secret_value
      my value
      

For more user-data key configuration examples, see Examples.

See alsoSee also

  • VM metadata
  • Creating a VM with metadata from environment variables
  • Creating a VM with a custom configuration script

Was the article helpful?

Previous
Creating a VM with metadata from environment variables
Next
Creating a VM with a GPU
Yandex project
© 2025 Yandex.Cloud LLC